建立並填充知識庫

原則——先確立基礎，再進行驗證。 知識庫是必須遵循的來源，而非參考建議。在 instructions 中界定其涵蓋範圍，並務必在依賴它之前確認實際問題能成功檢索——若搜尋結果為空，代理程式將回答「未涵蓋」。更多資訊請見 設計原則。

已掛載的知識庫會在每個回合自動檢索——模型不會決定是否要查找；相關性由向量距離決定。這是刻意如此設計的：知識庫是必須遵循的來源，而非可選工具。

1. 建立它

create_knowledge_base(
  name="Company policy",
  description="Mortgage policy and rates, effective 2026 — not car or personal loans",  # routes questions here
  instructions="Authoritative current mortgage policy; overrides any industry norm. "
               "Covers home mortgages only; for car or personal loans, say so and hand off.",  # for the model
)

名稱在建立時會正規化為 URL 安全的 slug——"Company policy" 會回傳為 company-policy。請使用這個回傳的名稱進行後續所有操作：add_knowledge_text(kb_name=…)、search_knowledge_base(kb_name=…)，以及將其附加至代理程式。稍後輸入原始帶空格的名称只會導致 404 錯誤。

2. 撰寫 description——它是將問題路由至此知識庫的依據

description 不是標題。在每次回答之前，平台會讀取每個已附加知識庫的描述，並決定此問題需要其中哪一個——如果都不需要，則完全不進行搜尋。否則，擁有三個知識庫的代理程式會在每個回合進行三次向量搜尋，並將三組摘錄倒入提示詞中，即使訪客只是說了「hi」。

因此，描述模糊或為空的知識庫會在不需要時被搜尋，而——更糟的是——在需要時被遺漏。這兩種失敗都不會發出警報：前者表現為帶有無關引用的緩慢回答，後者表現為「我沒有關於那方面的資訊」。

用訪客會使用的詞語撰寫一行，點明主題：

✅ "Country-by-country medical device registration requirements"
✅ "Regulatory change news by country and authority, 2022–2026 — what changed and when"
✅ "Selpercatinib — for lung and thyroid cancer"
 
❌ "Knowledge base"                ← routes nothing
❌ "Imported from the website"     ← says where it came from, not what is in it
❌ "Sandbox test, safe to delete"  ← says why it exists, not what is in it

重點在於與其他知識庫區分開來，而非篇幅長短。 擁有九個知識庫的租戶——八個藥品和一個公司簡介，每行一個，不超過十二個字——能正確路由 10 個問題中的 10 個，因為「肺癌和甲狀腺癌」與「IgA 腎病」絕不會混淆。這是經過測量的，而非假設。

僅在兩個知識庫重疊時添加邊界。 如果你的產品頁面和新聞檔案庫都討論同一主題，請說明哪一個是什麼——「……不包括定價或公司資訊」能阻止檔案庫回答定價問題。如果知識庫已經明顯不同，添加邊界條款毫無幫助。

這一行也是控制台列表顯示的內容，但這只是次要功能。

3. 從預期用途撰寫 instructions——在建立時，而非「稍後」

instructions 不影響檢索——檢索由向量搜尋和 max_distance 決定。它會在回答時注入到此知識庫摘錄旁邊，因此它規範模型如何使用其檢索到的內容。留空時，知識庫仍會檢索，但回答會失去所有知識庫特定規則：權威性、邊界、引用慣例。僅對於沒有特殊規則的通用參考材料，留空是可以接受的。

根據知識庫的實際使用方式推導出來——每個問題一行：

按知識庫類型劃分的知識庫指令範例：

# Website-content KB (products, services, team, blog)
instructions="Company website content: products, services, team and blog posts. Authoritative
for what we offer and who we are. Marketing copy is not a contractual promise — for prices,
terms or eligibility prefer the policy KB; if only this KB answers, attribute it to the website."
 
# Policy / regulation KB
instructions="Current company policy, effective 2026; overrides industry norms and prior
knowledge. Covers home mortgages only — for car or personal loans, say so and hand off.
Any quoted rate or fee must state its effective date."
 
# Product-docs KB
instructions="Official product documentation for the current release. State the version when a
feature is version-dependent. If the docs don't cover something, say so — never fill the gap
from general knowledge."

4. 新增內容

add_knowledge_text(kb_name="Company policy", title="2026 late-fee rule",
                   content="From 1 July 2026 the daily late fee is 0.019% …")

二進位檔案（pdf/docx）和整個資料夾（壓縮檔）透過 add_knowledge_file 處理——會遞迴遍歷子資料夾，並根據其在壓縮檔中的路徑匯入每個 md/txt/pdf/html/docx。

4b. 撰寫你希望被檢索到的句子

檢索匹配含義，而單獨的值幾乎沒有任何含義。這是你所能控制的單一最高槓桿點，而且很容易出錯，因為不會報錯——搜尋仍會回傳結果，只是不是正確的結果。

一個真實的客戶目錄在 1,500 筆記錄中的 1,480 筆包含這一行：

Reading level: 1 · Age: 5 · Words: 1951

而「哪些書適合剛開始獨立閱讀的兒童」回傳了一本關於音樂神童的書。事實就在文本中，但仍然無法觸及：1 與 beginner reader 的相似程度，遠不如一個詞與另一個詞的相似程度。

在值旁邊添加一句話即可修復——在該記錄上進行測量：

Reading level: 1 · Age: 5
Suitable for around age 5, for children just starting to read on their own.

（越低越接近。在此模型上，兩個無關段落大約在 0.61，因此最後一行從「僅略好於隨機」變為真正的匹配——且增益跨語言傳遞。）

規則：如果問題是通過屬性而非通過文本回答的——價格、日期、等級、可用性、庫存——請用文字說明。 結構化值用於過濾；檢索查找的是寫下的內容。

不值得你花時間做的事

匯出文件經常自我重複——summary 和 description 包含相同的文字。這看起來很浪費，而且直覺認為它「消耗」了向量是錯誤的：我們進行了測量，移除重複將檢索距離改變了 +0.002（跨越 60 筆記錄）——也就是說，毫無影響。嵌入是一個方向，而非預算；說同樣的話兩次主要指向同一方向兩次。

保留它。將精力花在上面的句子上。

4c. 如果文件共享標頭，建立結構化索引

向量搜尋無法計數、按數字過濾或分組。「你們有多少」、「哪些少於 200 字」、「每類別有多少」不是回答得不好——它們是結構上無法回答的，代理程式將拒絕回答或報告它偶然檢索到的少數記錄。

build_knowledge_index(name="books", roles=["identity", "link", "image"])

僅在文件共享機器可讀標頭時才值得調用——元數據表、YAML front matter、Field: value 行。產品匯出、目錄、傳單和課程列表通常符合資格；散文不符合，且調用會拒絕建立值各不相同的表。拒絕是正確的結果，而非需要繞過的錯誤。

roles 命名必須精確提取且永不改寫的字段：

詢問用戶這些字段是什麼；不要推斷。 哪一個 URL 是發送給客戶的，這是一個數據未陳述的事實。如果聲明的角色找不到，它會回傳在 roles.unresolved 中，並帶有候選字段名稱——將這些提供給用戶，而不是選擇一個。

讀取 dropped，並告知用戶

{"built": true, "documents": 4523,
 "columns": ["title", "age", "word_count", "genre", "read_url", "cover_url"],
 "dropped": [["isbn", "not_found", "no anchor 'ISBN: ' in the sample"]]}

被捨棄的列在其他地方不可見：後續回答只是繞過它，因此此報告是唯一提及它的地方。get_knowledge_index 也是如此，其警告通常會顯示客戶不知道的數據問題——在一個真實的目錄中，十分之一的記錄頁數為 0，這不是短書，而是將缺失值記錄為零，這會拉低基於它構建的每個平均值。

用客戶自己的術語報告這些內容。平台中沒有其他內容會這樣做。

稍後更改它

patch_knowledge_index(name="books", request="also track the author", apply=false)

先以 apply=false 運行，向用戶顯示將發生的更改，批量進行多項編輯，然後一次性應用。應用會從存儲的文本中重新讀取字段；它不會重新嵌入任何內容，因此成本很低。

詢問文件中不存在的內容會回傳帶有原因的 refused 條目——將該原因原樣傳遞給用戶，而不是發明繞過方案。

5. ★ 驗證檢索——不要跳過 ★

search_knowledge_base(kb_name="Company policy", query="how is the late fee calculated")
#   hits  → the agent can answer this
#   empty → the agent will treat it as "not covered" and say so

6. 掛載它

update_agent(name="Support", add_knowledge_bases=["company-policy"])   # incremental — keeps existing mounts

不要在 instructions 中寫「始終引用段落」——此行為已內建。僅撰寫此特定庫特有的內容：權威順序、覆蓋範圍邊界、特殊使用（例如「引用利率必須說明其生效日期」）。

回傳報告——不要止步於「已匯入」。 告訴用戶有多少分塊落地，並提供可點擊的鏈接以打開知識庫及其知識星圖（已攝取內容的 3D 視圖）：https://console.agent4.io/#/knowledge-bases/Company%20policy——然後確認它已附加至代理程式。