Sira AI

主题

知识库（Knowledge Base） ​

License 提示

"知识库"编排器需要 orchestrator.knowledge_base (PROFESSIONAL)。知识库本身（创建 / 上传 / 检索）当前未单独按 License 网关，但通常和上述编排器或 Agent 检索一起被消费。

Sira 的知识库每条都同时承载两条内容流，由查询时的 mode 决定调用哪条：

流存什么查什么
文档 RAG 流上传的文件解析后切块，向量 + 知识图谱模糊语义提问、长文档摘要、跨段落推理
QA 对流结构化的问答对 + 双向量索引标准答案、政策口径、客服 FAQ

重要事实更新

之前的文档说知识库由 RAG-Anything + LightRAG 双引擎 构成。代码里 RAG-Anything 已被移除（参见 services/rag_wrapper.py:1-7），当前使用：

  • LightRAG —— 唯一的检索引擎（向量 + 图谱混合）
  • 文档解析器 —— auto（默认）/ markitdown / vlm / mineru 四选一（在创建 KB 时配置；Docling 已于 2026-05 移除）

旧文档若提到 "RAG-Anything"，按本说明为准。

数据模型一图 ​

KnowledgeBase  ──┬──  kb_documents  ──→  LightRAG (PG 多 namespace)
                 │                       ├─ KV (chunk 文本)
                 │                       ├─ pgvector
                 │                       ├─ 知识图谱 (实体 + 关系)
                 │                       └─ doc_status
                 │
                 └──  qa_pairs       ──→  question_vector + answer_vector
                          │              (pgvector + ivfflat)
                          └─ qa_categories (树形)

kb_documents 是平台元数据；切片 / 向量 / 图谱实际存在 LightRAG 用 PG 命名空间隔离的表里。qa_pairs 是 Sira 自己管理的结构化表。

查询模式（mode 参数） ​

Mode走哪条流何时用
hybrid（默认）QA 优先，未命中走 LightRAG mix大多数场景
qa_only仅 QA 对严格答案场景（合规口径）
doc_only仅 LightRAG自由文本提问、研究类
mixLightRAG 混合（向量 + 图谱）主要给 doc_only 走，自由调用
local / global / naive / bypassLightRAG 原生模式调试 / 高级用法

混合模式的"先 QA 后 RAG"逻辑：

向量化 query
    │
    ▼
QA 对 pgvector 余弦搜 (threshold = 0.7 召回)
    │
    ├─ 最高相似度 ≥ 0.9 → 直接返回 QA 答案（短路）
    │
    └─ 否则 → 调 LightRAG (mix 模式) 检索文档片段
                │
                ├─ 可选 rerank（KB 配了 rerank_model_id 时启用）
                │
                ▼
            用 KB 配置的 LLM 融合两路结果生成最终回复

阈值不可配

0.7 / 0.9 阈值是 services/hybrid_kb_service.py 里的硬编码常量，不是配置项。如需精确"必须用 QA 答案"，请用 mode=qa_only。

创建知识库 ​

进入 /knowledge-base → "新建"，表单字段：

字段说明
name / display_name / description标识
llm_model_id检索结果融合用的 LLM
embedding_model_id向量化模型（必选）
vision_model_id文档里图片识别（可选）
rerank_model_id检索结果重排（可选）
parser_typeauto（默认，按文件类型自动选）/ markitdown / vlm / mineru（多模态最强，唯一支持 "i" 图像分析）
enable_image_processing是否对文档内图片调用 vision 模型
mineru_configlang / backend / device / source / vlm_url / formula / table
chunking_strategylength（默认）/ outline（按大纲） / semantic（语义边界）
chunking_config默认 1024 tokens chunk + 128 overlap，按 \n 切
language主语言（影响切分）

不存在"QA 库" vs "文档库"的类型选择——任何知识库都既能放文档也能加 QA 对。

文档摄入 ​

上传途径 ​

方式端点说明
单文件上传POST /knowledge-bases/{id}/documentsmultipart
单页 URL/documents/from-url抓单 URL
站点地图/documents/from-sitemap最多 500 页

支持的格式 ​

.pdf .docx .doc .xlsx .xls .pptx .ppt .txt .md

不支持独立上传图片 / 音频 / 视频

图片 / 音频 / 视频不能作为单独文件上传到知识库。文档内嵌的图片可由 MinerU + vision 模型识别提取，但 .png / .mp3 / .mp4 直接上传会被拒。

切分策略对比 ​

策略适用
length通用、最快。默认 1024 token + 128 overlap
outline文档有清晰章节结构（手册、政策）
semantic长篇议论 / 研究文献，按语义边界切

处理流程 ​

文件落到本地 RAG_WORKDIR_BASE/{kb_dir}/（默认 /app/data/rag_workdir/，非 MinIO），然后投递到 Celery 的 kb_queue_{kb_id} 队列处理：

upload → kb_documents.status=pending
   │
   ▼ Celery worker
parse (auto / markitdown / vlm / mineru)
   │
   ▼
chunk
   │
   ▼
embed
   │
   ▼
存入 LightRAG 命名空间
   │
   ▼
kb_documents.status = completed (或 failed + processing_error)

失败重试 ​

POST /knowledge-bases/{kb_id}/documents/{doc_id}/retry

仅当 status == failed 时允许。

QA 对管理 ​

字段 ​

字段说明
question / answer必填
question_vector / answer_vector双向量（默认 Vector(1024)）
category_id关联到 qa_categories 树
channelall / pc / mobile / hotline，做渠道隔离
tagsTEXT[]（不是 JSONB）
priority整数（不是 high/medium/low 枚举）
statusactive / archived / draft
view_count / match_count / feedback_score / last_matched_at命中统计

批量导入 CSV ​

POST /knowledge-bases/{kb_id}/qa-pairs/batch-import-csv

CSV 列（确切支持的）：question、answer、tags（管道或逗号分隔）、priority（整数）、source_id。

CSV 不识别这些列

  • category / category_name：CSV 不解析；如需归类请通过端点的 category_id query 参数指定
  • channel：CSV 不解析；通过 query 参数或导入后批量更新

类目树 ​

qa_categories 用 parent_id + path（形如 /1/3/7）实现树形：

GET /knowledge-bases/{kb_id}/qa-categories/tree

返回完整树状结构。

检索 API ​

POST /knowledge-bases/{kb_id}/query
{
  "query": "...",
  "mode": "hybrid",
  "top_k": 5,
  "max_tokens": 2048,
  "temperature": 0.3,
  "vlm_enhanced": false,
  "multimodal_content": null
}

返回包含 similarity 字段（不是 score）的检索片段 + LLM 融合后的最终回复。

单 KB 单查询

当前 /query 端点只支持 单个 KB。多 KB 联合检索发生在 Agent 层（见下方）。

让智能体使用知识库 ​

每个 Agent 可以挂多个 KB：

json
{
  "knowledge_base_ids": ["kb-uuid-1", "kb-uuid-2"],
  "retrieval_config": {
    "mode": "hybrid",
    "top_k": 5,
    "similarity_threshold": 0.7,
    "as_tool": false
  }
}

两种检索模式 ​

Passive 注入（as_tool=false，默认） ​

每次对话先检索所有挂载的 KB，把命中片段拼到用户消息前面，再交给 LLM。Agent 完全不知情、不能选择是否检索。

在 Supervisor 编排器里，passive 模式会被自动跳过——只有 tool 模式有效。

Tool 模式（as_tool=true） ​

注入一个名为 search_knowledge_base 的工具（统一名字，不是按 KB 分别命名），LLM 自主决定调不调、传什么 query。

工具命名是固定的

旧文档里写"系统会按 KB 名生成 search_企业微信文档 这种工具"——不正确。代码里所有 KB 的检索工具统一叫 search_knowledge_base，跨 KB 通过工具内部参数 knowledge_base_ids 选择。

知识库编排器 ​

OrchestrationType 第 8 项 KNOWLEDGE_BASE 用于"直答型"场景——不调度任何 Agent，进来的消息直接走 KB 检索 → 返回结果，端到端最快、最便宜。

配置：

json
{
  "kb_id": "...",
  "mode": "hybrid",
  "top_k": 5,
  "vlm_enhanced": false,
  "max_tokens": 2048,
  "temperature": 0.3
}

注：每个知识库编排器只能绑 一个 KB；需要跨多个 KB 的请用 Agent + multi-KB。

知识图谱 ​

LightRAG 在文档摄入时会自动构建实体 + 关系图。Sira 暴露给前端：

端点用途
/graph/data整图节点 + 边
/graph/stats节点 / 边数量
/graph/search?q=按关键词找子图
/graph/community/{id}查看社区聚类

/knowledge-base/[id] 详情页有"知识图谱"标签可视化（基于 vis-network）。

前端页面结构 ​

/knowledge-base/[id] 的标签：

标签内容
documents已上传文件列表，状态、操作
qaQA 对管理 + 类目树
graph知识图谱可视化
query查询 playground，可视化测试 mode / top_k
config修改 KB 设置（解析器、切分策略、模型等）

"chunks" 标签不存在

旧文档提过的 "chunks 标签 / 切片预览 UI" 在代码里没有。切片实际存在 LightRAG 内部，平台不暴露细粒度的切片浏览。

限制与未实现 ​

项状态
每组织最大 KB 数(none found)
单 KB 总大小上限(none found)，total_size_bytes 仅作统计
单文档大小上限未在 /documents 端点强制
站点抓取页数上限 500 页
关键字 / 全文检索（无向量化）不支持 —— 全部走向量 + 可选 rerank
QA 完全字面匹配不支持 —— 所有匹配都是向量
QA 版本管理 / 审核流不支持 —— status 是自由文本枚举
多语言 QA 同义合并不支持
检索结果缓存配置不支持

相关文档 ​

Apache-2.0 Licensed

Copyright © 2024 Sira AI Inc.