Skip to main content

代码库索引

代码库索引通过使用AI嵌入创建语义搜索索引，改变了itBuilder理解项目的方式。它不只是搜索确切的文本匹配，而是理解查询的含义，帮助Roo找到相关代码，即使您不知道特定的函数名或文件位置。


功能概述​

启用后，索引系统会:

  1. 解析您的代码 使用Tree-sitter识别语义块(函数、类、方法)
  2. 创建嵌入 使用AI模型为每个代码块创建嵌入
  3. 存储向量 在Qdrant数据库中存储向量以便快速相似性搜索
  4. 向Roo提供codebase_search工具 用于智能代码发现

这使得可以使用自然语言查询如"用户认证逻辑"或"数据库连接处理"来在整个项目中查找相关代码。

快速入门指南​

💰 完全免费的设置可用

您可以通过以下方式零成本设置代码库索引:

  • Qdrant Cloud(免费层)或Docker Qdrant(完全免费)
  • Google Gemini(目前免费)

这为您提供专业级语义搜索而无需任何订阅费用!

步骤1: 选择您的设置​

在启用代码库索引之前，您需要两个组件:

  1. 嵌入提供者 - 将代码转换为可搜索向量
  2. 向量数据库 - 存储和搜索这些向量

步骤2: 设置Qdrant(向量数据库)​

选项A: 云设置(推荐入门) - 免费​

  1. 在Qdrant Cloud注册(提供免费层)
  2. 创建一个集群
  3. 复制您的URL和API密钥

选项B: 本地设置 - 免费​

使用Docker:

docker run -p 6333:6333 qdrant/qdrant

使用Docker Compose:

version: '3.8'
services:
  qdrant:
    image: qdrant/qdrant
    ports:
      - "6333:6333"
    volumes:
      - qdrant_storage:/qdrant/storage
volumes:
  qdrant_storage:

步骤3: 设置嵌入提供者​

Google Gemini设置(推荐) - 免费​

  1. 从Google AI Studio获取API密钥(目前免费)
  2. 在itBuilder设置中:
    • 提供者: Google Gemini
    • API密钥: 您的Google AI Studio密钥
其他提供者可用

虽然本指南专注于目前免费的Google Gemini，但itBuilder也支持OpenAI、Ollama和OpenAI兼容的提供者。您可以在配置下拉菜单中探索这些选项。

步骤4: 保存​

  1. 点击保存并开始索引

状态指示器将显示:

  • 黄色(索引中): 当前正在处理文件
  • 绿色(已索引): 准备就绪可搜索
  • 红色(错误): 检查故障排除部分

管理和配置索引器​

您可以直接从itBuilder聊天界面监控状态并管理代码库索引器的所有配置。

状态图标​

在聊天输入的右下角，您会找到代码库索引状态图标。此图标提供了索引器当前状态的快速概览。

代码库索引状态图标

图标颜色表示状态:

  • 🟢 绿色: 已索引。索引是最新的，可以搜索。
  • 🟡 黄色: 索引中。系统正在积极处理文件。仍然可以执行搜索，但结果可能不完整。
  • 🔴 红色: 错误。发生了问题(例如无法连接到Qdrant或嵌入提供者)。请参阅故障排除部分获取帮助。
  • ⚪ 灰色: 待机。索引器等待配置或已禁用。

配置弹出窗口​

点击状态图标打开主配置弹出窗口。在这里，您可以查看详细状态并管理所有设置。

代码库索引弹出窗口
  • 状态: 显示当前状态的详细消息，如"已索引 - 文件监视器已启动"或正在进行扫描的进度。
  • 设置: 包含连接嵌入提供者和向量数据库的主要字段。
  • 高级配置: 允许您微调搜索参数，如相似度阈值。
  • 清除索引数据: 从Qdrant集合中删除所有数据并清除本地文件缓存。当您想从头开始重新索引整个项目时使用此功能。此操作无法撤销。
  • 保存: 应用您的配置更改。如果更改了关键设置(如API密钥或模型)，索引器将自动重新启动。

详细配置字段​

本指南解释配置弹出窗口中可用的每个设置。

代码库索引配置详情

设置字段​

  • 嵌入提供者

    • 目的: 选择生成AI嵌入的来源。
    • 行为: 此下拉菜单确定显示哪些配置字段。您的选项是OpenAI、Google Gemini、Ollama和OpenAI兼容。

  • API密钥(适用于OpenAI、Gemini、OpenAI兼容)

    • 目的: 与您选择的提供者进行身份验证的密钥。
    • 行为: 所有基于云的提供者都需要此输入，并安全存储在您的VS Code密钥存储中。

  • 基本URL(适用于Ollama、OpenAI兼容)

    • 目的: 连接到提供者API的端点。
    • 行为: 对于Ollama，这通常是http://localhost:11434。对于OpenAI兼容提供者如Azure，这是完整的部署URL。

  • 模型

    • 目的: 选择您想要使用的特定嵌入模型。
    • 行为: 可用模型列表根据所选提供者而变化。显示模型的向量维度(例如1536维度)，因为更改维度需要完全重新索引。

  • Qdrant URL

    • 目的: 您的Qdrant向量数据库的连接端点。
    • 行为: 这必须是有效的URL，指向您的本地或基于云的Qdrant实例(例如http://localhost:6333)。

  • Qdrant API密钥

    • 目的: 安全Qdrant实例的身份验证密钥。
    • 行为: 此字段是可选的，仅当您的Qdrant部署需要API密钥时才应使用。

高级配置字段​

  • 搜索分数阈值

    • 目的: 控制代码片段被视为匹配所需的最小相似度分数。
    • 行为: 使用滑块设置0.0到1.0之间的值。较低的值返回更多(但可能不太相关)的结果，而较高的值返回更少、更精确的结果。
    • 推荐设置:
      • 低(0.15-0.3): 更广泛的结果，适合探索
      • 中(0.4-0.5): 平衡精度和召回率(默认:0.4)
      • 高(0.6-0.8): 仅精确匹配

  • 最大搜索结果

    • 目的: 设置单个codebase_search返回的最大代码片段数。
    • 行为: 使用滑块调整限制。这有助于控制提供给AI的上下文量。

主要优势​

  • 语义搜索: 通过含义查找代码，而不仅仅是关键词
  • 增强AI理解: Roo可以更好地理解和处理您的代码库
  • 跨项目发现: 搜索所有文件，而不仅仅是打开的文件
  • 模式识别: 定位类似的实现和代码模式

文件处理方式​

智能代码解析​

系统使用复杂的解析策略:

  1. Tree-sitter优先: 对于支持的语言，使用AST解析识别语义代码块(函数、类、方法)
  2. Markdown支持: 通过将标题视为语义入口点来索引Markdown文件
  3. 智能回退: 对于不支持的文件类型，回退到基于行的分块

块大小:

  • 最小: 100字符
  • 最大: 1,000字符
  • 大型函数在逻辑边界处智能分割

文件过滤​

索引器尊重您项目的忽略模式:

  • 匹配.gitignore模式的文件
  • 匹配.rooignore模式的文件
  • 二进制文件和图像
  • 大于1MB的文件

重要: 确保您的.gitignore包含常见的依赖文件夹如node_modules、vendor、target等，因为系统完全依赖这些模式进行过滤。

增量更新​

  • 文件监视: 实时监控您的工作区变化
  • 智能更新: 仅重新处理修改的文件
  • 分支感知: 自动处理Git分支切换
  • 基于哈希的缓存: 避免重新处理未更改的内容

最佳实践​

编写有效查询​

与其搜索确切的语法:

  • ❌ const getUser
  • ✅ 从数据库获取用户的函数

使用自然语言描述:

  • "认证中间件"
  • "API请求的错误处理"
  • "数据库连接设置"

安全考虑​

  • API密钥: 安全存储在VS Code的加密存储中
  • 代码隐私: 仅发送小代码片段进行嵌入
  • 本地处理: 所有解析都在本地进行
  • 访问控制: 尊重文件权限和忽略模式

故障排除​

连接问题​

"连接到Qdrant失败"

  • 确保Qdrant正在运行(docker ps检查)
  • 验证URL匹配(默认:http://localhost:6333)
  • 检查防火墙/网络策略
  • 对于云实例，确认URL和API密钥

"无效API密钥"或"401未授权"

  • 仔细检查您的API密钥是否正确
  • 确保密钥具有必要的权限
  • 对于Ollama，验证服务是否正在运行

模型问题​

"找不到模型"

  • 对于Google Gemini: 确保模型名称正确(例如text-embedding-004)
  • 对于其他提供者: 查阅其文档了解可用模型和正确命名

索引问题​

"卡在错误状态"

  1. 首先检查连接问题
  2. 点击设置中的"清除索引并重新索引"
  3. 这解决了损坏的缓存或集合问题

"索引时间过长"

  • 对于大型代码库(10k+文件)是正常的
  • 检查.gitignore是否包含大型目录
  • 考虑向.rooignore添加模式

使用搜索功能​

索引完成后，Roo可以使用codebase_search工具:

自然语言查询示例:

  • "如何处理用户认证?"
  • "数据库连接设置"
  • "错误处理模式"
  • "API端点定义"
  • "组件状态管理"

该工具提供:

  • 相关代码片段
  • 带行号的文件路径
  • 相似度分数
  • 直接导航链接

隐私与数据安全​

您的代码保持私密:

  • 仅发送小代码块(100-1000字符)进行嵌入
  • 嵌入是单向数学表示
  • 本地解析意味着完整文件永远不会离开您的机器
  • 使用Ollama实现完全离线操作

数据存储:

  • 向量存储在您选择的Qdrant实例中
  • 您控制数据存储位置(本地/云)
  • 易于删除: 只需清除索引

当前限制​

  • 文件大小: 每个文件最大1MB
  • 单一工作区: 一次只能索引一个工作区
  • 外部依赖: 需要嵌入提供者+Qdrant
  • 语言支持: 使用Tree-sitter支持的语言效果最佳

未来增强​

计划改进:

  • 额外的嵌入提供者
  • 多工作区索引
  • 增强的过滤选项
  • 团队协作功能
  • VS Code原生搜索集成
  • 增量重新索引优化