知识库

概览

知识库是一个与领域无关的系统，将你的数据转化为结构化知识图谱。AI 智能体在对话期间搜索这个图谱，以提供准确、有据可查的回答，而不是凭空生成。

而且这是多人协作的。智能体可以在对话中将学到的内容自主写回到项目知识库中，所有其他智能体在下一次会话中都能读取 — 形成一个像人类组织记忆一样累积复利的闭环公司大脑。此外，服务于一个团队的单个智能体可以跨用户携带带归属的记忆，因此它可以用与用户 B 交谈时收集的上下文来回应用户 A。详见 智慧（Wisdom）与共享记忆（Shared Memory）。

项目（你的租户）
                            |
 +--------------------------+--------------------------+
 |                          |                          |
 v                          v                          v
智能体 A                   智能体 B                   智能体 C
 |                          |                          |
 |--- 写入已验证 ----------+                          |
 |    的事实                |                          |
 |                          |                          |
 |                  读取 + 为回答提供依据              |
 |                          |                          |
 |                          +--- 更新条目 ------------>|
 |                                                     |
 |                                          读取已强化的事实
 v                          v                          v
用户 X                     用户 Y                     用户 Z

 智能体之间：闭环。一个智能体学到的任何东西，项目内
 其他所有智能体都能立即获取。

 智能体内部：单个智能体也可以在它服务的用户之间共享
 记忆 — 带归属（sharedMemory）或不带归属（wisdom）。
 同一智能体、多位用户、共享上下文。

上传文档 / API 推送
     |
     v
提取实体 + 关系
     |
     v
构建知识图谱（去重节点 + 边）
     |
     v
运行分析规则（推荐、趋势）
     |
     v
智能体在对话中查询图谱

数据如何进入知识库

填充知识库有两种方式，外加一个可选能力，可以叠加在两者之上：

1. 手动上传。 通过 SDK 或仪表板上传 PDF、DOCX、Markdown 或纯文本文件。平台自动提取实体和关系并写入图谱。适用于你掌控的静态文档 — 手册、政策、产品说明、世界观。一次性，或在源变更时重新上传。→ 文档上传

2. 在增量变化时推送的 ETL 作业。 一次定义实体模式；让你的作业按计划、队列或变更数据捕获流调用 insertFacts 或 bulkUpdate。适用于实时上游真实源 — 数据库、价格数据流、CMS、爬虫 — 这样源一变 KB 就保持同步。Upsert 是幂等的：推同一标签两次会合并属性并增加版本号，因此同样的作业在任何节奏下重跑都是安全的。→ SDK：插入与搜索

+ 智能体自主编辑 (可选开关 — 按智能体或按项目全局启用／禁用)。打开 knowledgeBaseWrite 能力后，智能体获得 knowledge_create / knowledge_update / knowledge_delete 工具。在对话中智能体自己记录已验证的事实，每次写入都打上 source = "agent:<agent-id>" 的戳，并采用 compare-and-swap 更新语义，因此并发的管理员编辑不会被静默覆盖。当真相之源就是对话本身时使用 — 客服记录已验证的事故详情、客户成功捕获续约上下文、记录员智能体写会议记录等。

两条导入路径相互独立 — 用其中之一、两者、或都不用。自主编辑是按智能体的开关（或通过 default_agent_kb_write 设的项目级默认值），叠加在你已经在运行的任何导入路径之上。你始终保持掌控：每次智能体写入都在服务器端针对你的模式验证、按配额限制、范围限定到智能体自己的项目，且可逆 — 仅软删除，硬删除仍然只属于管理员。

手动上传                 增量变化时 ETL              对话中的智能体
 (PDF / DOCX / MD)        (insertFacts / bulkUpdate)  (knowledge_create / update / delete)
      |                          |                          |
      |                          |                          | 需要
      |                          |                          | knowledgeBaseWrite: true
      v                          v                          v
 +----------------------------------------------------------------+
 |                  项目知识图谱                                   |
 |   实体 + 关系 + 版本历史 + 审计追踪                            |
 +----------------------------------------------------------------+
                            |
                            v
            智能体在每次对话中通过
            knowledge_search 查询

两种数据导入方式

1. 文档上传

上传 PDF、DOCX、Markdown 或纯文本文件。平台自动处理文档，提取实体和关系，并将其添加到知识图谱中。

import fs from "fs";

const doc = await client.knowledge.uploadDocument(projectId, {
file: fs.createReadStream("product_catalog.pdf"),
fileName: "product_catalog.pdf",
});

console.log(doc.documentId, doc.status); // "processing"

2. API 推送（结构化数据）

以编程方式推送结构化数据——非常适合爬虫、库存信息流、价格追踪器或任何外部数据源。

await client.knowledge.insertFacts(projectId, {
source: "inventory_sync",
facts: [
  {
    entityType: "product",
    label: "Widget Pro X",
    properties: {
      price:    29.99,
      category: "electronics",
      inStock:  true,
      tags:     ["wireless", "bluetooth"],
    },
  },
],
relationships: [
  { fromLabel: "Widget Pro X", toLabel: "Electronics", edgeType: "belongs_to" },
],
});

SDK：插入与搜索

使用 SDK 从你的服务器推送数据并执行搜索：

import { Sonzai } from "@sonzai-labs/agents";

const client = new Sonzai({ apiKey: "sk-..." });

// 插入实体
await client.knowledge.insertFacts(projectId, {
source: "price_sync",
facts: [
  {
    entityType: "item",
    label: "Charizard Base Set",
    properties: { price: 450, trend: "+12%", condition: "PSA 10" },
  },
],
relationships: [
  { fromLabel: "Charizard Base Set", toLabel: "Fire Pokemon", edgeType: "is_type" },
],
});

// 搜索
const results = await client.knowledge.search(projectId, {
query: "fire pokemon under 500",
type: "item",
limit: 10,
});
for (const r of results.results) {
console.log(r.label, r.properties);
}

SDK：批量更新

使用 bulkUpdate 批量同步外部数据（价格、库存、统计数据）。只有变更的字段才会更新——适合频繁同步。

await client.knowledge.bulkUpdate(projectId, {
source: "price_sync",
updates: [
  { label: "Charizard Base Set", entityType: "item", properties: { price: 460 } },
  { label: "Blastoise Base Set", entityType: "item", properties: { price: 390 } },
],
});

实体模式

定义带类型字段的自定义实体类型。模式指导提取，让平台精确知道要寻找哪些字段。支持的类型：string、number、boolean、date、enum、array。

await client.knowledge.createSchema(projectId, {
entityType: "pokemon_card",
description: "Collectible trading cards",
fields: [
  { name: "price",     type: "number", required: true },
  { name: "condition", type: "enum",   enumValues: ["PSA 10", "PSA 9", "Raw"] },
  { name: "set",       type: "string", required: true },
  { name: "rarity",    type: "enum",   enumValues: ["Common", "Uncommon", "Rare", "Ultra Rare"] },
  { name: "tags",      type: "array" },
],
similarityConfig: {
  enabled: true,
  threshold: 0.7,
  fieldWeights: { price: 0.3, set: 0.4, rarity: 0.3 },
},
});

知识图谱

实体通过类型化关系相互连接。图谱支持任意实体类型和关系类型——完全与领域无关。

搜索

对所有实体标签和属性进行全文搜索。支持类型过滤、属性过滤和图谱遍历以包含关联实体。

const results = await client.knowledge.search(projectId, {
query:   "bluetooth speaker",
type:    "product",
limit:   10,
filters: { in_stock: true },
});

for (const r of results.results) {
console.log(r.label, r.score, r.properties);
// r.related[] 包含 1 跳遍历得到的关联节点
}

推荐引擎

定义规则，根据字段匹配将源实体与目标实体匹配。引擎防止反馈循环，并通过转化反馈随时间改进推荐。

// 创建推荐规则
const rule = await client.knowledge.createAnalyticsRule(projectId, {
ruleType: "recommendation",
name: "Similar cards",
config: { matchFields: ["set", "rarity"], limit: 5 },
enabled: true,
});

// 获取推荐
const recs = await client.knowledge.getRecommendations(
projectId, rule.ruleId, sourceNodeId, 5
);
for (const rec of recs.results) {
console.log(rec.label, rec.score);
}

// 记录反馈（改进未来推荐）
await client.knowledge.recordFeedback(projectId, {
ruleId:       rule.ruleId,
sourceNodeId: sourceNodeId,
targetNodeId: rec.nodeId,
action:       "converted",  // "shown" | "converted"
});

趋势分析

追踪实体属性在时间窗口（7天、30天、90天）内的变化。获取涨幅最大、跌幅最大、波动最大和均值最高的排名。

// 获取趋势排名
const trends = await client.knowledge.getTrendRankings(projectId, {
ruleId: ruleId,
type:   "top_gainers",   // "top_gainers" | "top_losers" | "most_volatile" | "highest_avg"
window: "30d",           // "7d" | "30d" | "90d"
limit:  10,
});

for (const item of trends.rankings) {
console.log(item.label, item.currentValue, item.changePercent);
}

智能体如何使用知识库

在对话期间，AI 智能体可以使用 knowledge_search 工具查询知识库。智能体从你的图谱中获取准确数据（包括实体属性、关系和推荐），而不是凭空生成事实。

用户："500 美元以下最好的卡牌是什么？"
     |
     v
智能体调用 knowledge_search("cards under 500")
     |
     v
知识库返回：Charizard（$450，+12%）、Blastoise（$380，+8%）
     |
     v
智能体："Charizard Base Set 售价 $450，本月涨幅 12%——
      500 美元以内的绝佳投资选择。"

智慧（Wisdom）与共享记忆（Shared Memory）

除了静态文档，与众多用户对话的智能体会沉淀出模式——重复的行为、共同的目标、稳定的偏好。Sonzai 通过两个互补的层级把这种跨用户的归纳能力暴露出来：智慧（wisdom）（去归属，默认开启）和共享记忆（shared memory）（带归属，需主动开启）。

Wisdom（去归属，默认开启）

当 wisdom 能力开启时（每个新建智能体都默认开启），平台每日运行一个推广任务：从每位用户的事实历史中抽取模式，做 k-匿名化处理，再通过 LLM 改写为去归属的知识。任何个体用户都无法被识别。每个智能体都能享受到「这种做法通常有效 / 这类话题常常出现」的好处，而不会泄露任何人说过什么。

这是你的免费归纳层。智能体无需调用任何工具——只要能力开启，wisdom 会自动出现在智能体的上下文中。

// 每个新建智能体的 wisdom 默认开启。如果某个具体智能体不需要跨用户归纳
//（例如单用户陪伴产品），可以在创建时或通过 updateCapabilities 显式关闭：
await client.agents.updateCapabilities("agent_abc", { wisdom: false });

Shared Memory（带归属，需主动开启）

某些业务想要的恰好是去归属的反面——他们希望使用同一智能体的多位用户能看到谁在做什么。一个团队协作智能体可能会显示「Alice 负责迁移，Bob 负责事故响应」；一个派对协调智能体可能记录「Carol 带甜点，Dave 负责布置」。这就是 sharedMemory 能力所控制的。

开启该能力后，智能体会记录带人/实体归属的事实（角色、专长、业务上下文、关系边），并把它们暴露给共享该智能体的其他用户。三件事会发生变化：

1. 工具。 智能体获得 wisdom_create、wisdom_update、wisdom_delete 以及关系边工具，加上后台的 CSV 导入。
2. 上下文。 其他用户的归属事实会带着归属信息出现在智能体的每轮上下文中。
3. 隐私底线。 每次写入都会先经过隐私黑名单（薪酬、健康、政治）的语义校验后再持久化——即使用户主动要求，智能体也不能跨用户分享不该分享的内容。

Shared memory 默认关闭。仅在智能体服务于一个群组、团队或派对，且这种跨用户可见性确实有价值时才显式开启。

// Wisdom 是前置条件（新智能体默认 ON——只有当你要覆盖默认值时才显式传）。
await client.agents.updateCapabilities("agent_abc", {
wisdom:       true,
sharedMemory: true,
});

也可以在创建智能体时直接开启：

const agent = await client.agents.create({
name:       "Team Coordinator",
project_id: "proj_abc",
tool_capabilities: {
  wisdom:        true,
  shared_memory: true,
},
});

使用场景

API 参考

所有端点使用 Authorization: Bearer {api_key} 请求头。

实际应用

每类受众都会使用知识库——但上传什么以及如何查询各不相同。

await client.knowledge.insertFacts("project-id", {
  entities: [
    { label: "Aunt Miriam", type: "person", properties: { relation: "mentor", alive: false } },
    { label: "The old observatory", type: "place", properties: { significance: "first-love" } },
  ],
});