知识库

两种方式，怎么选？

• 本地知识库：适合 PDF、Word、Markdown 等文件和网页内容，在本机建立索引，无需额外服务。
• 外部知识库：适合已有 HTTP 检索接口、Dify / FastGPT、企业搜索或 MCP 只读查询工具。
• 外部连接为只读：HiRocky 仅保存配置并在问答时读取结果，不会写入或修改远端内容。
• 两者可同时使用；建议按业务划分，例如本地放产品手册，外部接工单或 CRM。

本地知识库

在「知识库」页面创建并管理，所有资料与索引均保存在本机。

1. 创建知识库

   点击新建，填写名称与说明（如「产品文档」「个人笔记」），便于后续在智能体中识别和绑定。

2. 导入资料

   支持 TXT、Markdown、PDF、Word、PPT、Excel、RTF 等格式，也可通过网页导入在线内容。导入后系统会自动抽取文本并建立检索索引。

3. 备份与导出

   需要迁移或备份时，可在知识库页面导出。本地库适合存放不常变动、希望完全离线管理的资料。

在 HiRocky 中添加外部知识库

1. 创建连接

   打开「知识库」→ 切换到「外部知识库」→「添加外部知识库」。填写名称与描述，选择连接类型：HTTP 搜索接口 或 MCP Tool，然后保存。

2. 配置 HTTP 连接（若选 HTTP）

   填写接口地址（完整 URL）、适配类型、返回条数、超时（秒）。可选：API Key、Headers JSON、Filters JSON。保存后点击「测试」，确认能返回样例结果。

3. 配置 MCP 连接（若选 MCP）

   先在「设置 → MCP」添加 server、测试连接、刷新并启用目标 tool，再回到「外部知识库」选择 MCP Tool 类型，选中对应 server / tool 后保存。

HTTP 通用约定

所有 HTTP 外部知识库均使用 POST 请求，Content-Type: application/json。接口须返回 JSON（HTTP 状态码 2xx），HiRocky 从响应体中解析结果数组与每条片段的文本字段。

请求鉴权：填写 API Key 时，HiRocky 会附加请求头 Authorization: Bearer <API_KEY>。若接口需要其它鉴权头，在 Headers JSON 中填写，例如：

{
  "X-API-Key": "your-api-key",
  "X-Workspace-ID": "workspace_001"
}

注意：同时填写 API Key 与 Headers JSON 时，HiRocky 会同时发送 Bearer Token 与自定义 Headers。

标准搜索接口

在 HiRocky 中选择「标准搜索接口」时，会向你的 URL 发送以下 JSON 请求体：

{
  "query": "用户问题",
  "limit": 6,
  "filters": {}
}

推荐响应格式（出参）：使用 results 数组，每条包含完整字段，便于 HiRocky 展示来源与分数：

{
  "results": [
    {
      "id": "chunk_001",
      "title": "退款政策",
      "content": "用户可在付款后 7 天内申请退款。",
      "source": "售后手册",
      "url": "https://example.com/docs/refund",
      "score": 0.91,
      "metadata": {
        "section": "billing"
      }
    }
  ]
}

也支持直接返回 JSON 数组（无 results 包装），每条至少包含可读内容字段：

[
  {
    "title": "退款政策",
    "content": "用户可在付款后 7 天内申请退款。"
  }
]

Dify 响应适配

选择「Dify 响应适配」时，HiRocky 发送的请求体在标准字段基础上增加 top_k：

{
  "query": "用户问题",
  "limit": 6,
  "top_k": 6,
  "filters": {}
}

HiRocky 按以下顺序查找结果数组（出参）：records → documents → data.records → data.documents → data → results。Dify 常见返回示例：

{
  "data": {
    "records": [
      {
        "id": "dify_001",
        "segment": {
          "content": "SLA 可用性为 99.9%。"
        },
        "document": {
          "name": "SLA.md",
          "url": "https://example.com/sla"
        },
        "metadata": {
          "score": 0.73
        }
      }
    ]
  }
}

正文通常从 segment.content 读取；标题可从 document.name 等字段解析。测试时若找不到数组，会提示：Knowledge source response must include a result array.

FastGPT 响应适配

选择「FastGPT 响应适配」时，HiRocky 发送的请求体增加 topK（注意大小写）：

{
  "query": "用户问题",
  "limit": 6,
  "topK": 6,
  "filters": {}
}

HiRocky 按以下顺序查找结果数组（出参）：data.list → data.records → data → results → list。FastGPT 常见返回示例：

{
  "data": {
    "list": [
      {
        "id": "fg_001",
        "q": "如何重置密码？",
        "a": "打开设置页，点击发送重置邮件。",
        "sourceName": "FAQ",
        "similarity": 0.82
      }
    ]
  }
}

若单条结果没有 content，但同时包含 q 与 a，HiRocky 会自动组合为： Q: 如何重置密码？ A: 打开设置页，点击发送重置邮件。

HTTP 返回字段兼容映射

三种适配类型共用同一套字段映射。每条结果必须能解析出「内容」字段，否则该条会被忽略；若整个响应没有可解析的结果数组，测试会失败。

自建接口最小示例

下面是一个 Node.js + Express 最小实现，演示如何接收 HiRocky 标准请求并返回 results：

import express from "express";

const app = express();
app.use(express.json());

app.post("/v1/knowledge/search", async (req, res) => {
  const { query, limit = 6, filters = {} } = req.body;

  const results = [
    {
      id: "doc_001_chunk_001",
      title: "示例知识",
      content: `这是和「${query}」相关的示例内容。`,
      source: "internal-handbook",
      url: "https://example.com/handbook/doc_001",
      score: 0.88,
      metadata: { filters }
    }
  ].slice(0, limit);

  res.json({ results });
});

app.listen(3000, () => {
  console.log("Knowledge API listening on http://localhost:3000");
});

MCP Tool 接入

MCP 适合：内部系统只读查询、数据库只读查询、文档服务、已有 MCP server 暴露的企业 API。工具的数据访问范围与权限由 MCP server 决定，建议仅授予只读权限。

1. 在设置中启用 MCP

   打开「设置」→「MCP」→ 添加或启用 MCP server → 测试连接 → 刷新工具 → 确认目标 tool 已启用。

2. 创建外部知识库连接

   「知识库」→「外部知识库」→「添加外部知识库」→ 连接类型选 MCP Tool → 选择已同步的 server / tool → 保存。

3. 绑定智能体

   在智能体中开启知识库能力并勾选该连接。MCP 外部知识库为 tool-only：不会像 HTTP 一样每次对话自动 POST 检索，而是作为智能体可用工具，在知识查询或 MCP 调用意图明确时参与回答。

智能体绑定与参数建议

• 面向固定业务场景的智能体，只绑定该场景需要的知识库，避免无关片段进入上下文。
• 本地知识库与外部知识库内容重叠时，明确分工（如本地放产品手册，外部接工单 / CRM）。
• HTTP 外部知识库：检索模式选「自动检索」，对话时自动请求你的接口。
• MCP 外部知识库：保持工具调用模式，由对话流程按意图触发。
• 返回条数：建议从 4～6 开始；片段很短可适当调高，片段很长应调低以免占满上下文。
• 超时：建议 3～8 秒；企业内网接口较慢可增加，最高不超过 30 秒。

安全与数据边界

• 外部知识库为只读，HiRocky 不会向远端写入知识内容。
• 连接配置（URL、Headers、Filters、检索模式、返回条数、超时）保存在本机。
• API Key 从配置 JSON 中剥离，写入 knowledge_source_secrets，并使用应用本地密钥加密。
• Headers JSON 以明文保存在本地配置中，请勿存放除非你能接受本地存储方式的高敏感密钥。
• 启用 HTTP「自动检索」时，用户问题会发送给已绑定且启用的外部接口；不符合合规要求时不要启用自动检索。
• MCP 工具权限由对应 server 控制，建议优先只读。

绑定到智能体

无论本地还是外部知识库，都需要在智能体中显式绑定后才会生效。

1. 开启并选择知识库

   进入「智能体」设置，开启知识库能力，勾选要使用的本地库或外部连接。面向固定业务场景时，只绑定该场景需要的库，减少无关检索干扰。

2. 在对话中验证

   绑定完成后发起提问，HiRocky 会检索相关片段并纳入上下文，回答中可保留来源与引用信息。切换到专家模式，可查看检索步骤、工具调用和失败原因，便于确认知识库是否正常工作。

常见问题与排查

测试连接失败

• 接口地址须能从运行 HiRocky 的本机访问（注意 localhost 与内网 IP）。
• 接口须接受 POST，Content-Type: application/json。
• 检查 API Key、Headers JSON 是否与你的服务鉴权方式一致。
• 确认在配置的超时时间内返回，且 HTTP 状态码为 2xx。

测试成功但没有样例

• 响应 JSON 须包含可解析的结果数组。
• 标准适配：优先提供 results 数组。
• Dify 适配：优先 data.records 或 records。
• FastGPT 适配：优先 data.list 或 list。
• 每条结果须含 content、text、segment.content、chunk.content、answer，或同时含 q 与 a。

智能体回答未引用外部知识库

• 外部知识库连接已启用，且智能体已开启知识库能力并完成绑定。
• HTTP：检索模式为「自动检索」。
• MCP：对应 tool 已在设置中启用；问题需有明确查询意图。
• 打开专家运行视图，查看是否出现外部知识库检索步骤及报错信息。

• 本地库：导入失败可换用 TXT / Markdown，或检查文件是否损坏。
• 面向固定业务场景的智能体，只绑定该场景需要的知识库，避免无关片段进入上下文。
• 本地知识库与外部知识库内容重叠时，明确分工（如本地放产品手册，外部接工单 / CRM）。