知識庫

两种方式，怎么选？

• 本機知識庫：适合 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）。