name: rag-administration description: 管理和优化RAG（检索增强生成）系统，包括重新索引、搜索优化和自定义索引创建。当用户想要提高搜索质量、重新索引其集合或创建专业索引时使用。 tools:

reindex_collection
optimize_search
create_custom_index
search_custom_index
list_custom_indexes
view_settings
update_settings

RAG系统管理

管理支持知识库搜索和问答的检索增强生成（RAG）系统。这是一项用于优化搜索质量和管理向量数据库的高级技能。

概述

RAG系统包括：

混合搜索 - 语义（pgvector）+ BM25（tsvector）与互惠排名融合
重新排序 - 基于LLM（零成本）或Cohere API进行精确重新评分
智能体检索 - 具有查询扩展、文档评分和幻觉检查的自校正多步骤管道（可选，在混合搜索之上运行）
向量存储 - 存储用于语义搜索的嵌入（PostgreSQL + pgvector）
索引 - 嵌入的有组织集合
设置 - 分块、嵌入模型、搜索、重新排序和智能体检索的配置

核心功能

工具	目的	何时使用
`reindex_collection`	重建整个RAG索引	重大更改后、新嵌入模型或数据问题
`optimize_search`	调整搜索参数	当搜索结果不够相关时
`create_custom_index`	创建专业主题索引	需要快速检索的专注研究领域
`search_custom_index`	在自定义索引中搜索	查询专业索引
`list_custom_indexes`	查看可用自定义索引	检查存在的索引

何时使用此技能

当用户出现以下情况时使用RAG管理：

报告搜索结果差或答案不相关
想要提高搜索质量
拥有需要优化的大型集合
想要为特定主题创建专注索引
正在更改RAG设置并需要重新索引

重新索引集合

何时重新索引

需要重新索引的情况：

设置中的嵌入模型已更改
分块参数已更改
索引似乎损坏
添加/删除了大量文章
搜索质量显著下降

重新索引工作流程

步骤1：检查当前设置
view_settings(section="rag")
→ 显示当前嵌入模型、分块大小、重叠

步骤2：（可选）根据需要调整设置
update_settings(
  section="rag",
  updates={
    "chunk_size": 1000,
    "chunk_overlap": 200,
    "embedding_model": "text-embedding-3-small"
  }
)

步骤3：运行重新索引
reindex_collection(
  force=true,  # 即使索引存在也强制重建
  batch_size=100  # 分批处理
)

步骤4：监控进度
get_task_status(task_type="reindex")

重新索引注意事项

时间：完全重新索引可能需要10-60分钟，具体取决于集合大小
成本：为所有内容生成嵌入（如果使用OpenAI则有API成本）
可用性：重新索引期间搜索使用旧索引工作

搜索优化

调整搜索参数

optimize_search(
  min_relevance_score=0.7,  # 过滤阈值
  max_results=20,           # 每个查询的最大结果数
  hybrid_search=true,       # 结合语义+关键词
  rerank=true               # 使用重新排序模型
)

理解搜索参数

参数	效果	推荐值
`min_relevance_score`	更高=更严格的匹配	0.7用于精确度，0.5用于召回率
`max_results`	限制检索到的分块数	10-20用于问答，50+用于综合
`hybrid_search`	添加关键词匹配	适用于技术术语
`rerank`	重新评分顶部结果	适用于更高质量

诊断搜索问题

1. 检查索引状态
   list_custom_indexes()
   → 查看存在的索引及其状态

2. 测试搜索
   search_articles(query="测试查询")
   → 检查结果是否相关

3. 调整阈值
   optimize_search(min_relevance_score=0.6)
   → 降低阈值以获得更多结果

4. 验证设置
   view_settings(section="rag")
   → 确认配置正确

自定义索引

自定义索引的用例

主题聚焦：仅索引关于“机器学习”的论文以加快搜索
时间范围：仅索引近期论文（2023-2024）
作者集合：索引特定研究组的论文
项目特定：索引特定研究项目的论文

创建自定义索引

create_custom_index(
  name="ml_transformers_2024",
  description="2024年Transformer论文",
  filter_criteria={
    "tags": ["transformers", "attention"],
    "year_min": 2024
  },
  include_full_text=true
)

管理自定义索引

# 列出所有索引
list_custom_indexes()
→ 显示：main, ml_transformers_2024, protein_research

# 搜索特定索引
search_custom_index(
  index_name="ml_transformers_2024",
  query="高效注意力机制"
)

RAG设置参考

关键设置（通过view_settings/update_settings）

{
  "rag": {
    "embeddingModel": "text-embedding-3-small",
    "collectionName": "thoth_papers",
    "chunkSize": 500,
    "chunkOverlap": 50,
    "topK": 5,
    "hybridSearchEnabled": true,
    "hybridSearchWeight": 0.7,
    "rerankingEnabled": true,
    "rerankerProvider": "auto",
    "rerankerModel": "google/gemini-2.5-flash",
    "contextualEnrichmentEnabled": false,
    "adaptiveRoutingEnabled": false,
    "qa": {
      "model": "anthropic/claude-3-5-sonnet",
      "temperature": 0.1
    },
    "agenticRetrieval": {
      "enabled": false,
      "maxRetries": 2,
      "documentGradingEnabled": true,
      "queryExpansionEnabled": true,
      "queryDecompositionEnabled": true,
      "hallucinationCheckEnabled": true,
      "strictHallucinationCheck": false,
      "webSearchFallbackEnabled": false,
      "confidenceThreshold": 0.5
    }
  }
}

设置详情

设置	目的	备注
`hybridSearchEnabled`	结合语义+BM25搜索	准确率提高约35%，无额外成本
`hybridSearchWeight`	平衡（0.0=仅BM25，1.0=仅语义）	推荐0.7
`rerankingEnabled`	使用更强大的模型重新评分结果	提高约20-30%
`rerankerProvider`	`auto`（如果有密钥则使用Cohere，否则使用LLM）、`cohere`或`llm`	推荐自动
`contextualEnrichmentEnabled`	在索引时为每个分块添加LLM上下文	昂贵，默认禁用
`adaptiveRoutingEnabled`	对查询进行分类以进行路由	实验性，默认禁用

智能体检索设置

设置	目的	备注
`agenticRetrieval.enabled`	智能体检索的主开关	关闭时标准RAG仍有效
`agenticRetrieval.maxRetries`	低置信度时的最大重试循环次数	2是良好的默认值，更高成本更高
`agenticRetrieval.documentGradingEnabled`	LLM为每个文档评分相关性	过滤掉检索中的噪声
`agenticRetrieval.queryExpansionEnabled`	生成语义查询变体	帮助找到使用不同术语的论文
`agenticRetrieval.queryDecompositionEnabled`	将复杂查询分解为子问题	适用于多跳问题
`agenticRetrieval.hallucinationCheckEnabled`	验证答案基于来源	捕获无支持的声明
`agenticRetrieval.strictHallucinationCheck`	严格=每个声明直接在来源中陈述	宽松模式允许合理推断
`agenticRetrieval.confidenceThreshold`	文档评分的最小相关性分数	更低=更多文档通过，更高=更严格

更改嵌入模型

警告：更改嵌入模型需要完全重新索引！

步骤1：更新设置
update_settings(
  section="rag",
  updates={"embedding_model": "text-embedding-3-large"}
)

步骤2：强制重新索引
reindex_collection(force=true)

分块策略

集合类型	chunk_size	chunk_overlap	理由
短论文	500	100	较小的分块以提高精确度
长论文	1500	300	每个分块更大的上下文
混合	1000	200	平衡的默认值
密集技术内容	800	200	更多重叠以获取上下文

工作流程示例

示例1：提高搜索质量

用户：“我的搜索结果不太相关”

1. 检查当前配置
   view_settings(section="rag")
   → 当前：min_relevance=0.8, hybrid=false

2. 优化参数
   optimize_search(
     min_relevance_score=0.6,
     hybrid_search=true,
     rerank=true
   )

3. 测试搜索
   search_articles(query="用户主题")
   → 更好的结果

4. 响应：
   “我已调整您的搜索设置：
   - 降低相关性阈值（0.8 → 0.6）以获得更多结果
   - 启用混合搜索以改善关键词匹配
   - 启用重新排序以提高顶部结果质量

   请再次尝试搜索，并告诉我是否有所改善。”

示例2：设置更改后的完全重新索引

用户：“我更改了嵌入模型，需要重新索引吗？”

1. 检查设置
   view_settings(section="rag")
   → embedding_model: text-embedding-3-large

2. 确认需要重新索引
   “是的，更改嵌入模型需要完全重新索引。
   这将为所有文章重新生成嵌入。

   当前集合：约500篇论文
   预计时间：15-20分钟

   是否继续重新索引？”

3. 执行重新索引
   reindex_collection(
     force=true,
     batch_size=50
   )

4. 监控
   get_task_status(task_type="reindex")
   → 进度：250/500篇文章已处理

5. 完成
   “重新索引完成！所有500篇文章现在都使用text-embedding-3-large。
   搜索现在应该可以使用新的嵌入。”

示例3：创建研究主题索引

用户：“我想要一个专门针对我的强化学习论文的专注索引”

1. 创建自定义索引
   create_custom_index(
     name="reinforcement_learning",
     description="关于RL、策略梯度和决策制定的论文",
     filter_criteria={
       "tags": ["reinforcement-learning", "rl", "policy-gradient", "q-learning"]
     }
   )
   → 索引已创建，包含47篇论文

2. 确认
   “已创建'reinforcement_learning'索引，包含47篇论文。

   要搜索此专注索引：
   - 使用search_custom_index，index_name='reinforcement_learning'

   这将为RL查询提供更快、更专注的结果。”

智能体检索管理

启用/禁用

# 启用智能体检索
update_settings(
  section="rag",
  updates={
    "agenticRetrieval": {"enabled": true}
  }
)

# 仅禁用幻觉检查（如果过于激进）
update_settings(
  section="rag",
  updates={
    "agenticRetrieval": {"hallucinationCheckEnabled": false}
  }
)

调整智能体检索

如果智能体检索答案慢但准确，减少重试次数：

update_settings(
  section="rag",
  updates={"agenticRetrieval": {"maxRetries": 1}}
)

如果太多不相关文档通过评分，提高阈值：

update_settings(
  section="rag",
  updates={"agenticRetrieval": {"confidenceThreshold": 0.7}}
)

如果查询扩展引入了离题论文，禁用它：

update_settings(
  section="rag",
  updates={"agenticRetrieval": {"queryExpansionEnabled": false}}
)

何时推荐智能体检索

当用户出现以下情况时建议启用：

提出复杂综合问题并获得浅显答案
抱怨结果中缺少相关论文
需要跨集合进行多跳推理

当用户出现以下情况时建议禁用或调整：

报告答案对其工作流程来说太慢
注意到幻觉检查器标记了合理的推断
拥有小型集合，标准RAG已经运行良好

最佳实践

性能

对大型集合重新索引时使用batch_size为50-100
为频繁搜索的主题创建自定义索引
仅当质量比速度更重要时才启用重新排序

质量

对具有特定术语的技术领域使用混合搜索
如果缺少相关结果，降低相关性阈值（0.5-0.6）
如果上下文丢失，增加分块重叠

维护

添加100+篇新文章后重新索引
定期审查自定义索引的相关性
通过用户反馈监控搜索质量

故障排除

未找到结果

1. 检查索引是否存在：list_custom_indexes()
2. 降低阈值：optimize_search(min_relevance_score=0.4)
3. 验证文章是否存在：collection_stats()
4. 如果损坏则强制重新索引：reindex_collection(force=true)

搜索缓慢

1. 检查索引大小：list_custom_indexes()
2. 为常见查询创建专注索引
3. 在optimize_search中减少max_results
4. 为速度禁用重新排序

结果不一致

1. 检查集合中是否有重复文章
2. 验证嵌入模型是否未更改而未重新索引
3. 强制清理重新索引：reindex_collection(force=true)