開始使用 Knowledge Base API

了解 Knowledge Base API 如何組織內容、處理文件，以及執行 AI 操作，讓您可以針對平台建置應用程式。

此 API 支援管理集合與文件、處理內容，以及套用 AI 功能 (例如問答、摘要、搜尋和結構化擷取) 的工作流程。使用此頁面了解這些元素如何協同運作，然後使用 API 參考資料來了解端點層級的實作詳細資訊。

開始之前

請確認您擁有：

• 存取 Knowledge Base 的權限。
• 為您的應用程式設定的 API 存取權。
• 存取集合的權限或建立集合的權限。
• 目前的端點定義和方案適用的 Knowledge Base API 參考資料。

如果您尚未設定 API 存取權，請參閱設定 Knowledge Base API 存取權。

API 運作方式

典型的 Knowledge Base API 工作流程會遵循此序列：

驗證 → 集合 → 文件 → 索引 → 推論 → 回答

收藏

集合會定義您應用程式的知識領域。建立集合時，回應中包含唯一命名空間，您可以在後續操作中使用此命名空間。

例如：

{
"namespace": "<collection-namespace>",
"name": "example-collection"
}

請保留集合命名空間，以供文件和推論要求使用。

文件

文件會上傳到集合並指派唯一的文件識別碼。

上傳回應會識別文件，讓您的應用程式可以追蹤處理情況，並在之後順應請求參考該文件。

{
"document_id": "<document-id>",
"document_name": "example.pdf"
}

構建索引

上傳文件和建立索引是分開的階段。

上傳會將檔案轉移到 Knowledge Base。索引會擷取其內容並處理該內容，以供 AI 操作使用。

您的應用程式應確認處理已完成，然後再對文件提交推論要求。

推論

推論操作會將 Knowledge Base AI 功能套用至處理的內容。

可用的操作包含：

• 問答
• 文件摘要
• 內容搜尋
• 結構化屬性擷取

使用 API 參考，判定您想要執行的作業的端點和請求方案。

回應

推論回應會傳回產生的結果，並可包含支援的歸因資訊。

根據作業，歸因資料可識別與結果相關的來源內容、頁面和座標。您的應用程式決定如何將該資訊呈現給使用者。

執行基本 API 工作流程

最簡單的應用程式工作流程是建立集合、新增文件、等待處理，然後執行推論作業。

了解文件處理

文件生命週期會影響您的應用程式何時可以使用所上傳的內容。

這種區別對於自動化工作流程特別重要。應用程式應檢查處理狀態，而不是在上傳後立即發送推論請求。

選擇推論操作

根據您的應用程式需要對來源內容執行的操作，來選擇操作。

問答

使用問答功能來提交關於集合或文件內容的自然語言問題。

API 提供串流和非串流問答。

「串流問答」會在回應產生的同時，以漸進方式傳回。當您的介面應漸進地顯示生成的內容時，請使用此功能。

串流問答也支援控制是否將自訂指示套用至請求。您也可以控制是否為串流問答回答產生推理。

「非串流問答」會等候產生完成並返回完成的回答。當您的應用程式不需要顯示部分輸出時使用此功能。

摘要

使用摘要，產生文件內容的精簡表示法。

API 參考定義了目前的請求需求，和受支援的輸入。

內容搜尋

使用內容搜尋來檢索與指定搜尋文字相關的內容。

這可以協助應用程式識別相關的來源素材，而無需產生對話回答。

屬性擷取

當您的應用程式需要從文件內容中取得結構化值時，請使用擷取。

擷取定義可以識別以下資訊：

屬性名稱：contract_value
類型：integer
描述：Agreement contract value
提示：擷取美元計價的最大協議值。

傳回的結果，可以包含擷取的值、信心資訊和來源歸因。

控制操作使用的內容

API 提供幾種方式來確定哪些內容參與請求。

集合和文件

使用收藏集和文件識別碼來定義操作可用的主要內容。

文件標記

標記與文件相關聯，而不是與收藏集相關聯。

文件標記只能透過 Knowledge Base API 使用，不會在標準使用者介面中顯示。

您可以搭配受支援的操作使用標記，來篩選請求所考量的文件。例如，應用程式可以將一組文件標記為財務文件，並將問題限制在帶有該標記的文件中。

附件

附件與收藏集文件是分開的。

將附件新增至對話不會將該檔案新增至收藏集。附件仍可為產生的回應提供內容，以及集合內容和聊天記錄。

當您的應用程式需要臨時或對話特定內容，而無需永久新增到收集中時，請使用附件端點。

使用歸因資料

推論回答可包含歸因資訊，將生成式輸出與支援來源內容連結。

歸因資料可包含以下資訊：

• 支援文字
• 文件資訊
• 頁碼
• 頁面座標

API 會將此資訊以資料形式提供。您的應用程式負責決定如何呈現此資訊。

例如，應用程式可以使用傳回的座標來建置來源反白顯示體驗，識別支援產生之答案的位置。

處理存取權和請求失敗

API 操作使用已驗證身分可用的權限。

如果已驗證身分缺乏對所請求收集、文件或操作的存取權，請求可能會失敗。

疑難排解時：

• 審閱傳回的 HTTP 狀態和回應。
• 確認已驗證身分可以存取請求的資源。
• 在執行推論之前，確認文件處理已成功完成。
• 確認請求中提供的識別碼正確無誤。
• 擷取在回應標頭中傳回的 X-Request-ID。

X-Request-ID 可識別跨 知識庫服務的請求，並可協助支援調查失敗的請求。

實作考量

• 單一上傳請求最多支援 200 個檔案。其他檔案可透過後續請求上傳。
• 上傳和索引是獨立的操作。
• 文件應在用於推論之前達到完成處理狀態。
• 附件是獨立資源，不會自動新增至集合。
• 標記屬於文件，可讓受支援的操作用來篩選來源內容。
• 使用 API 參考資料作為目前端點、參數、結構描述和支援操作的權威來源。

繼續開發

若想要使用可運作的範例來示範應用程式中的這些概念時，請使用 Python 示範。

開始使用 Knowledge Base Python 示範

當您準備好實施特定操作時，請使用 API 參考資料。

開啟 Knowledge Base API 參考資料