用途
RAG Knowledge Base 用于在 full-stack-ai-agent-template 项目中操作检索增强生成（RAG）知识库，包括摄取文档、执行语义搜索、管理集合，以及添加同步源/连接器（Google Drive、S3）。
RAG 栈位于 backend/app/services/rag/，包含摄取（ingestion）、向量存储（vectorstore）、嵌入（embeddings）与连接器（connectors）模块。检索能力以 search_knowledge_base 工具的形式暴露给智能体，同时通过 CLI 和仪表盘供操作人员使用。
主要能力
- 文档摄取：解析 → 分块 → 嵌入 → 写入向量存储（{{ cookiecutter.vector_store }}）。重复摄取同一来源会更新内容，可用 --no-replace / --sync-mode 控制去重。
- 语义搜索：对指定集合执行语义检索。
- 集合管理：列出集合、查看分块/向量统计、删除集合。
- 同步源（连接器）：按计划保持集合与外部源（Google Drive、S3/MinIO）同步，可按组织在仪表盘（/orgs/[id]/integrations）或通过 CLI 管理。
- 连接器凭据使用 CHANNEL_ENCRYPTION_KEY（Fernet）加密存储。
- 检索调优：分块大小/重叠与解析器（PyMuPDF / LlamaParse）通过环境变量配置；启用重排序（Cohere 或本地 CrossEncoder）可改善结果排序。
使用方式
CLI（在 backend/ 目录下运行）：
uv run {{ cookiecutter.project_slug }} cmd rag-ingest ./docs/ --collection docs --recursive # 摄取文件/文件夹
uv run {{ cookiecutter.project_slug }} cmd rag-search "your question" --collection docs # 语义搜索
uv run {{ cookiecutter.project_slug }} cmd rag-collections # 列出集合
uv run {{ cookiecutter.project_slug }} cmd rag-stats # 分块/向量计数
uv run {{ cookiecutter.project_slug }} cmd rag-drop <collection> --yes # 删除集合
同步源（连接器）：
uv run {{ cookiecutter.project_slug }} cmd rag-sources # 列出
uv run {{ cookiecutter.project_slug }} cmd rag-source-add # 添加（交互式）
uv run {{ cookiecutter.project_slug }} cmd rag-source-sync --all # 触发同步
添加新连接器类型：在 backend/app/services/rag/connectors/ 中参照现有 Google Drive / S3 连接器实现，在连接器注册表中注册，并暴露其配置字段。参见 docs/howto/add-sync-connector.md 与 docs/howto/configure-sync-sources.md。
检索调优：分块大小/重叠与解析器（PyMuPDF / LlamaParse）通过环境变量配置，参见 docs/configuration.md 与 docs/rag.md。启用重排序（Cohere 或本地 CrossEncoder）可改善结果排序。
适用场景
- 为智能体提供基于知识库的检索问答能力。
- 将本地文档或文件夹批量导入向量存储并执行语义搜索。
- 通过连接器将 Google Drive、S3/MinIO 等外部数据源按计划同步到知识库集合。
- 按组织管理集成与同步源。
限制与注意事项
- 嵌入提供者与维度按项目固定（{{ cookiecutter.embedding_provider }}），不要在同一集合中混用不同嵌入；更改后需重新摄取。
- 重型摄取作为后台任务运行，而非在请求中内联执行。
- 若搜索效果不佳：确认集合已填充（rag-stats）、检查聊天 KB 选择器中激活的集合、验证嵌入提供者/密钥。
- 完整流水线参考见 docs/rag.md。
（注：文中 {{ cookiecutter.* }} 为项目模板占位符，实际值由项目生成时确定。）