知识库与 RAG 集成指南

概述

知识库 (Knowledge Base) 是智航云 AI 中台的核心能力之一，基于 RAG (检索增强生成) 技术，让 AI 能够引用你的私有数据来回答问题。

工作流程如下：

上传文档 → 自动分块 → 向量化 → 存入向量数据库
                                        ↓
用户提问 → 语义搜索 → 获取相关片段 → AI 生成回答（引用知识库内容）

创建知识库

cURLPythonNode.js

bash

curl -X POST https://api.invoratec.cn/v1/knowledge \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "运维知识库",
    "description": "设备运维标准操作流程和故障排查手册",
    "type": "general"
  }'

python

kb = claw.knowledge.create(
    "运维知识库",
    description="设备运维标准操作流程和故障排查手册",
    type="general"
)
kb_id = kb["_id"]

javascript

const kb = await claw.knowledge.create({
  name: '运维知识库',
  description: '设备运维标准操作流程和故障排查手册',
  type: 'general'
})
const kbId = kb._id

知识库类型

type	说明
`general`	通用知识库，适用于大多数场景
`faq`	FAQ 问答库，适合结构化的问答对
`manual`	操作手册，适合长文档

上传文档

将文本内容上传到知识库，系统会自动进行分块和向量化处理。

cURLPythonNode.js

bash

curl -X POST https://api.invoratec.cn/v1/knowledge/KB_ID/documents \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "冷水机故障排查手册",
    "content": "## 常见故障\n\n### 高压报警\n原因：冷凝器散热不良...\n\n### 低压报警\n原因：制冷剂不足...",
    "metadata": {
      "category": "maintenance",
      "equipment": "chiller",
      "version": "v3.2"
    }
  }'

python

# 上传单个文档
claw.knowledge.upload(
    "## 常见故障\n### 高压报警\n原因：冷凝器散热不良...",
    knowledge_id=kb_id,
    title="冷水机故障排查手册",
    metadata={"category": "maintenance", "equipment": "chiller"}
)

# 批量上传（读取本地文件）
import os
docs_dir = "./maintenance_docs"
for filename in os.listdir(docs_dir):
    with open(os.path.join(docs_dir, filename), "r", encoding="utf-8") as f:
        content = f.read()
    claw.knowledge.upload(
        content,
        knowledge_id=kb_id,
        title=filename,
        metadata={"source": "local_file"}
    )

javascript

// 上传单个文档
await claw.knowledge.uploadDocument(kbId, {
  title: '冷水机故障排查手册',
  content: '## 常见故障\n### 高压报警\n原因：冷凝器散热不良...',
  metadata: { category: 'maintenance', equipment: 'chiller' }
})

// 批量上传
const fs = require('fs')
const path = require('path')
const docsDir = './maintenance_docs'
for (const file of fs.readdirSync(docsDir)) {
  const content = fs.readFileSync(path.join(docsDir, file), 'utf-8')
  await claw.knowledge.uploadDocument(kbId, {
    title: file,
    content,
    metadata: { source: 'local_file' }
  })
}

metadata 字段

metadata 是自定义的键值对，用于文档的分类和过滤。常用字段：

字段	说明	示例
`category`	文档分类	`maintenance`, `safety`, `training`
`version`	文档版本	`v3.2`
`department`	所属部门	`运维部`
`priority`	优先级	`high`, `medium`, `low`

语义查询 (RAG)

上传文档后，即可进行语义搜索。系统会对查询文本进行向量化，与知识库中的文档片段进行语义匹配。

cURLPythonNode.js

bash

curl -X POST https://api.invoratec.cn/v1/knowledge/KB_ID/query \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "冷水机高压报警怎么处理？",
    "limit": 5
  }'

python

results = claw.knowledge.query(kb_id, "冷水机高压报警怎么处理？")
for r in results:
    print(f"[{r['source']}] {r['text'][:100]}...")

javascript

const { results } = await claw.knowledge.query(kbId, {
  query: '冷水机高压报警怎么处理？',
  limit: 5
})
results.forEach(r => {
  console.log(`[${r.source}] ${r.text.slice(0, 100)}...`)
})

响应示例：

json

{
  "results": [
    {
      "text": "### 高压报警\n原因：冷凝器散热不良，通常由冷却水温度过高或水流量不足引起...",
      "source": "冷水机故障排查手册",
      "metadata": { "category": "maintenance", "equipment": "chiller" }
    },
    {
      "text": "当冷水机出现高压报警时，应首先检查冷却塔风机运行状态...",
      "source": "应急处理流程",
      "metadata": { "category": "emergency" }
    }
  ]
}

直接写入内容

除了通过 /documents 端点上传文档外，还可以使用 /content 端点直接写入知识内容：

bash

curl -X POST https://api.invoratec.cn/v1/knowledge/KB_ID/content \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "2026年新规：所有冷水机需每月进行一次冷媒检测...",
    "metadata": {
      "title": "2026年运维新规",
      "effective_date": "2026-01-01"
    }
  }'

AI 对话中使用知识库

当 AI 中台配置了知识库后，AI 对话会自动引用知识库内容：

bash

curl -X POST https://api.invoratec.cn/v1/ai/chat \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "B1 层冷水机报高压报警了，怎么处理？",
    "systemPrompt": "你是设备运维助手。请根据知识库内容回答问题，给出具体步骤。"
  }'

AI 会先在知识库中搜索相关内容，然后基于搜索结果生成回答。

实战示例：HR 知识库

以智航云DHR人力资源平台为例：

python

# 1. 创建知识库
hr_kb = claw.knowledge.create("HR政策库", description="人事制度与政策文档")

# 2. 上传各类文档
docs = [
    ("员工手册", "## 入职流程\n1. 签订劳动合同...\n\n## 考勤制度\n工作时间：9:00-18:00..."),
    ("薪酬制度", "## 薪资结构\n基本工资 + 绩效奖金 + 补贴...\n\n## 发薪日\n每月15日..."),
    ("请假制度", "## 年假\n工作满1年：5天...\n\n## 病假\n需提供医院证明..."),
]

for title, content in docs:
    claw.knowledge.upload(content, knowledge_id=hr_kb["_id"], title=title)

# 3. 测试查询
results = claw.knowledge.query(hr_kb["_id"], "年假有多少天？")
print(results[0]["text"])
# → "## 年假\n工作满1年：5天..."

知识库管理

列出知识库

bash

curl https://api.invoratec.cn/v1/knowledge \
  -H "X-API-Key: claw_xxxx"

列出文档

bash

curl https://api.invoratec.cn/v1/knowledge/KB_ID/documents \
  -H "X-API-Key: claw_xxxx"

列出文档时不返回完整内容（content 字段被排除），仅返回标题和 metadata。

最佳实践

合理分割文档。每个文档控制在 1000-5000 字为佳，过长的文档建议拆分。
使用有意义的标题。标题会作为搜索结果的 source 返回。
丰富 metadata。便于后续过滤和分类管理。
定期更新内容。过时的知识库内容会导致 AI 给出错误的回答。
多知识库隔离。不同业务领域使用不同的知识库，避免互相干扰。

下一步

知识图谱指南 -- 用图谱管理实体间的关系
AI 集成指南 -- 在 AI 对话中充分利用知识库
API 参考: 知识库 -- 完整 API 端点文档

知识库与 RAG 集成指南 ​

概述 ​

创建知识库 ​

知识库类型 ​

上传文档 ​

metadata 字段 ​

语义查询 (RAG) ​

直接写入内容 ​

AI 对话中使用知识库 ​

实战示例：HR 知识库 ​

知识库管理 ​

列出知识库 ​

列出文档 ​

最佳实践 ​

下一步 ​

知识库与 RAG 集成指南

概述

创建知识库

知识库类型

上传文档

metadata 字段

语义查询 (RAG)

直接写入内容

AI 对话中使用知识库

实战示例：HR 知识库

知识库管理

列出知识库

列出文档

最佳实践

下一步