为智能体配置知识库 — 文档上传、数据源管理、向量检索和 RAG 质量评估。

知识库管理

概述

知识库是 RAG（Retrieval-Augmented Generation，检索增强生成）的基础设施。通过将你的私有文档、网页、数据库等数据源导入知识库，智能体在对话时可以自动检索相关内容并生成准确的回答，而无需将所有数据塞进提示词。

典型的 RAG 流程如下：

用户提问
  → 将问题转换为向量
  → 在知识库中检索最相关的文档块
  → 将检索到的内容作为上下文注入 LLM 提示词
  → LLM 基于上下文生成回答

创建知识库

通过 Dashboard 创建

进入 Tensor Agent 管理面板 → 知识库
点击 创建知识库
填写基本信息：
- 名称 — 知识库的显示名称
- 描述 — 用途说明，方便团队协作
- 嵌入模型 — 选择文本嵌入模型（默认 text-embedding-3-small）
- 分块策略 — 选择文档切割方式（详见下文）
点击 确认创建

通过 API 创建

curl -X POST https://agent.tos.run/api/knowledge-bases \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "产品文档",
    "description": "产品使用手册和 FAQ",
    "embeddingModel": "text-embedding-3-small",
    "chunkingStrategy": {
      "type": "recursive",
      "chunkSize": 512,
      "chunkOverlap": 64
    }
  }'

响应示例：

{
  "id": "kb_01JQXYZ",
  "name": "产品文档",
  "description": "产品使用手册和 FAQ",
  "embeddingModel": "text-embedding-3-small",
  "chunkingStrategy": {
    "type": "recursive",
    "chunkSize": 512,
    "chunkOverlap": 64
  },
  "sourcesCount": 0,
  "chunksCount": 0,
  "createdAt": "2026-04-14T10:00:00Z"
}

数据源类型

知识库支持三种数据源类型，满足不同场景的数据接入需求。

文件上传

支持上传 PDF、Markdown、TXT、DOCX、CSV 等常见格式。单个文件大小限制为 50MB。

# 上传文件作为数据源
curl -X POST https://agent.tos.run/api/sources \
  -H "Authorization: Bearer $TOKEN" \
  -F "knowledgeBaseId=kb_01JQXYZ" \
  -F "type=file" \
  -F "file=@./product-manual.pdf"

URL 爬取

输入一个或多个 URL，系统自动爬取页面内容并索引。支持设置爬取深度和页面数量限制。

curl -X POST https://agent.tos.run/api/sources \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "knowledgeBaseId": "kb_01JQXYZ",
    "type": "url",
    "config": {
      "urls": ["https://docs.example.com"],
      "crawlDepth": 2,
      "maxPages": 100
    }
  }'

数据库连接

连接 PostgreSQL、MySQL 等数据库，将指定表或查询结果导入知识库。适合将结构化业务数据纳入智能体的知识范围。

curl -X POST https://agent.tos.run/api/sources \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "knowledgeBaseId": "kb_01JQXYZ",
    "type": "database",
    "config": {
      "driver": "postgresql",
      "connectionString": "postgresql://user:pass@host:5432/db",
      "query": "SELECT id, title, content FROM articles WHERE published = true",
      "contentColumn": "content",
      "metadataColumns": ["id", "title"]
    }
  }'

分块策略

文档在索引前会被切割成多个"块"（chunk），分块策略直接影响检索质量。

参数	说明	建议值
`type`	分块算法。`recursive` 按语义递归切割；`fixed` 按固定字符数切割	`recursive`
`chunkSize`	每个块的目标字符数	256 ~ 1024
`chunkOverlap`	相邻块之间的重叠字符数，避免在切割边界丢失上下文	chunkSize 的 10% ~ 20%
`contextualRetrieval`	是否启用上下文检索增强。开启后会为每个块附加文档级摘要，提升检索准确率	推荐开启

分块大小选择指南

较小的块（256~512） — 检索精度更高，适合 FAQ、条目式内容
较大的块（512~1024） — 保留更多上下文，适合长篇技术文档、操作手册

上下文检索（Contextual Retrieval）

启用后，系统会在索引阶段为每个块生成一段简短的上下文描述，拼接在块内容之前。这让孤立的文档块在被检索时也能携带足够的背景信息。

{
  "chunkingStrategy": {
    "type": "recursive",
    "chunkSize": 512,
    "chunkOverlap": 64,
    "contextualRetrieval": true
  }
}

启用上下文检索会增加索引时间和 Token 消耗，但通常能显著提升检索质量。建议在文档量可控的场景下优先开启。

同步与索引

数据源添加后，系统会自动触发首次索引。后续你可以手动触发重新索引以更新内容。

触发重新索引

curl -X POST https://agent.tos.run/api/sources/src_01JQABC/sync \
  -H "Authorization: Bearer $TOKEN"

响应示例：

{
  "sourceId": "src_01JQABC",
  "status": "syncing",
  "startedAt": "2026-04-14T10:30:00Z"
}

查看同步状态

可以通过查询数据源详情获取同步状态和日志：

curl https://agent.tos.run/api/sources/src_01JQABC \
  -H "Authorization: Bearer $TOKEN"

{
  "id": "src_01JQABC",
  "knowledgeBaseId": "kb_01JQXYZ",
  "type": "file",
  "status": "synced",
  "chunksCount": 142,
  "lastSyncedAt": "2026-04-14T10:32:15Z",
  "syncLog": {
    "documentsProcessed": 1,
    "chunksCreated": 142,
    "errors": []
  }
}

同步状态说明：

状态	说明
`pending`	等待处理
`syncing`	正在索引中
`synced`	索引完成
`failed`	索引失败，查看 `syncLog.errors` 获取错误详情

向量检索

知识库创建并索引完成后，你可以通过 API 执行向量搜索，获取与查询最相关的文档块。

基本搜索

curl -X POST https://agent.tos.run/api/knowledge-bases/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "knowledgeBaseId": "kb_01JQXYZ",
    "query": "如何配置自动备份",
    "topK": 5
  }'

响应示例：

{
  "results": [
    {
      "chunkId": "chunk_01JQ001",
      "content": "自动备份配置步骤：1. 进入系统设置 → 备份管理...",
      "score": 0.92,
      "metadata": {
        "sourceId": "src_01JQABC",
        "fileName": "product-manual.pdf",
        "pageNumber": 45
      }
    },
    {
      "chunkId": "chunk_01JQ002",
      "content": "备份策略支持按天、按周、按月三种频率...",
      "score": 0.87,
      "metadata": {
        "sourceId": "src_01JQABC",
        "fileName": "product-manual.pdf",
        "pageNumber": 46
      }
    }
  ]
}

搜索参数

参数	类型	必填	默认值	说明
`knowledgeBaseId`	`string`	是	—	知识库 ID
`query`	`string`	是	—	搜索查询文本
`topK`	`number`	否	`5`	返回最相关的前 K 个结果
`scoreThreshold`	`number`	否	`0.0`	最低相似度阈值，过滤低质量结果
`filter`	`object`	否	—	按 metadata 字段过滤

带过滤条件的搜索

curl -X POST https://agent.tos.run/api/knowledge-bases/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "knowledgeBaseId": "kb_01JQXYZ",
    "query": "退货政策",
    "topK": 3,
    "scoreThreshold": 0.7,
    "filter": {
      "sourceId": "src_01JQABC"
    }
  }'

查看文档分块

导入数据后，可以检查文档被切割成的块内容，确认分块效果是否合理。

# 获取知识库中的分块列表
curl "https://agent.tos.run/api/knowledge-bases/kb_01JQXYZ/chunks?page=1&pageSize=20" \
  -H "Authorization: Bearer $TOKEN"

响应示例：

{
  "data": [
    {
      "id": "chunk_01JQ001",
      "content": "自动备份配置步骤：1. 进入系统设置 → 备份管理...",
      "tokenCount": 128,
      "metadata": {
        "sourceId": "src_01JQABC",
        "fileName": "product-manual.pdf",
        "pageNumber": 45
      }
    }
  ],
  "total": 142,
  "page": 1,
  "pageSize": 20
}

如果发现分块效果不理想（如关键段落被截断、块太大导致检索不精确），可以调整分块策略后重新索引：

# 更新知识库的分块策略
curl -X PATCH https://agent.tos.run/api/knowledge-bases/kb_01JQXYZ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chunkingStrategy": {
      "type": "recursive",
      "chunkSize": 384,
      "chunkOverlap": 48,
      "contextualRetrieval": true
    }
  }'

# 然后重新索引所有数据源
curl -X POST https://agent.tos.run/api/sources/src_01JQABC/sync \
  -H "Authorization: Bearer $TOKEN"

质量评估

Tensor Agent 内置了知识库检索质量评估功能，帮助你在上线前验证检索效果。

运行评估

提供一组测试问题和期望的答案片段，系统会自动执行检索并评估结果。

curl -X POST https://agent.tos.run/api/knowledge-bases/eval \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "knowledgeBaseId": "kb_01JQXYZ",
    "testCases": [
      {
        "query": "如何配置自动备份",
        "expectedContent": ["系统设置", "备份管理", "定时任务"]
      },
      {
        "query": "退货政策是什么",
        "expectedContent": ["7天无理由", "退货流程"]
      },
      {
        "query": "API 调用频率限制",
        "expectedContent": ["100次/分钟", "rate limit"]
      }
    ],
    "topK": 5
  }'

评估结果

{
  "knowledgeBaseId": "kb_01JQXYZ",
  "summary": {
    "totalCases": 3,
    "avgRecall": 0.85,
    "avgPrecision": 0.78,
    "avgScore": 0.89
  },
  "results": [
    {
      "query": "如何配置自动备份",
      "recall": 1.0,
      "precision": 0.8,
      "avgScore": 0.91,
      "matchedExpected": ["系统设置", "备份管理", "定时任务"],
      "missedExpected": []
    },
    {
      "query": "退货政策是什么",
      "recall": 0.5,
      "precision": 0.6,
      "avgScore": 0.83,
      "matchedExpected": ["7天无理由"],
      "missedExpected": ["退货流程"]
    },
    {
      "query": "API 调用频率限制",
      "recall": 1.0,
      "precision": 0.8,
      "avgScore": 0.94,
      "matchedExpected": ["100次/分钟", "rate limit"],
      "missedExpected": []
    }
  ]
}

评估指标说明

指标	说明
`recall`	召回率。期望内容中有多少被检索到的块覆盖
`precision`	精确率。检索到的块中有多少是与查询相关的
`avgScore`	平均相似度分数。检索结果与查询的平均向量相似度

建议在调整分块策略或新增数据源后重新运行评估，确保检索质量没有下降。

API 参考

以下是知识库相关的所有 REST API 端点。所有请求需携带 Authorization: Bearer <token> 头。

知识库管理

方法	路径	说明
`POST`	`/api/knowledge-bases`	创建知识库
`GET`	`/api/knowledge-bases`	获取知识库列表
`PATCH`	`/api/knowledge-bases/:id`	更新知识库配置
`DELETE`	`/api/knowledge-bases/:id`	删除知识库及其所有数据

数据源管理

方法	路径	说明
`POST`	`/api/sources`	添加数据源
`DELETE`	`/api/sources/:id`	删除数据源
`POST`	`/api/sources/:id/sync`	触发数据源重新索引

检索与评估

方法	路径	说明
`POST`	`/api/knowledge-bases/search`	向量搜索
`POST`	`/api/knowledge-bases/eval`	检索质量评估

Node.js 示例

const BASE_URL = 'https://agent.tos.run/api';
const headers = {
  'Authorization': `Bearer ${token}`,
  'Content-Type': 'application/json',
};

// 创建知识库
const kb = await fetch(`${BASE_URL}/knowledge-bases`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: '产品文档',
    embeddingModel: 'text-embedding-3-small',
    chunkingStrategy: { type: 'recursive', chunkSize: 512, chunkOverlap: 64 },
  }),
}).then(r => r.json());

// 上传文件
const form = new FormData();
form.append('knowledgeBaseId', kb.id);
form.append('type', 'file');
form.append('file', fileBlob, 'manual.pdf');

const source = await fetch(`${BASE_URL}/sources`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}` },
  body: form,
}).then(r => r.json());

// 等待索引完成后搜索
const results = await fetch(`${BASE_URL}/knowledge-bases/search`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    knowledgeBaseId: kb.id,
    query: '如何配置自动备份',
    topK: 5,
  }),
}).then(r => r.json());

console.log(results);

Python 示例

import requests

BASE_URL = "https://agent.tos.run/api"
headers = {"Authorization": f"Bearer {token}"}

# 创建知识库
kb = requests.post(f"{BASE_URL}/knowledge-bases", headers=headers, json={
    "name": "产品文档",
    "embeddingModel": "text-embedding-3-small",
    "chunkingStrategy": {"type": "recursive", "chunkSize": 512, "chunkOverlap": 64},
}).json()

# 上传文件
with open("manual.pdf", "rb") as f:
    source = requests.post(f"{BASE_URL}/sources", headers=headers,
        data={"knowledgeBaseId": kb["id"], "type": "file"},
        files={"file": f},
    ).json()

# 搜索
results = requests.post(f"{BASE_URL}/knowledge-bases/search", headers=headers, json={
    "knowledgeBaseId": kb["id"],
    "query": "如何配置自动备份",
    "topK": 5,
}).json()

for r in results["results"]:
    print(f"[{r['score']:.2f}] {r['content'][:80]}...")

知识库管理

目录