開始使用知識庫 Python 示範

執行、檢查並調整常見 Knowledge Base API 工作流程的 Python 實作。

Python 示範為應用程式開發提供了一個具備實際功能的起點。使用完整工作流程來檢視集合建立、文件處理以及 AI 推論的共同運作，然後探索針對特定集合和推論操作的個別指令碼。

開始之前

請確認您擁有：

• 存取 Knowledge Base API。
• 驗證應用程式所需的認證。
• Python 3.7 或更新版本。建議使用 Python 3.11 或更新版本。
• 可用於完整示範工作流程的 PDF 檔案。

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

下載並設定 Python 示範

該示範使用requests、pyyaml 和tqdm。認證儲存在 config.yaml 中，驗證權杖受到自動管理。

請勿將 config.yaml 或產生的 .token 檔案提交到版本控制系統。

執行完整工作流程

執行:

python knowledgebase.py

若要使用特定的 PDF：

python knowledgebase.py --document=<path-to-pdf>

此示範：

1. 使用 API 驗證。
2. 建立名為 demo-collection 的收藏。
3. 上傳 PDF。
4. 監視文件直到索引完成。
5. 對已處理的文件執行推論要求。

上傳和索引是文件導入的不同部分。索引會擷取文件內容，並使其可供 AI 操作使用。

如果您未指定 PDF，此示範會從套件的 documents 目錄中選取其一。如果文件處理未達到完成狀態，將會在五分鐘後逾時。

探索集合操作

執行完整工作流程後，使用個別指令碼來探索特定的 API 操作。

建立集合

python collection.py --action create --name <collection-name>

收藏名稱最多可包含 255 個字元。

列出收藏

python collection.py --action list

在提示時選擇要列出由您建立、由您共用或由其他人共用的收藏。

共用收藏

python collection.py --action share --collection-id <collection-id>

輸入在系統提示時應收到讀取或寫入存取權的電子郵件。

上傳文件

python collection.py --action upload --collection-id <collection-id> --path=<path-to-file-or-directory>

指令碼可以上傳單一檔案或來自指定目錄的文件。

列出集合中的文件

python collection.py --action get_documents --collection-id <collection-id>

檢查文件處理狀態

python collection.py --action get_status --document-id <document-id>

本示範將這些操作提供為獨立的範例，供您在完整工作流程之外進行檢查與調整。 

探索推論操作

推論範例需要集合識別碼和文件識別碼。使用集合指令碼來識別它們：

python collection.py --action list
python collection.py --action get_documents --collection-id <collection-id>

問答

列出您的集合和文件，然後執行問答範例：

python collection.py --action list
python collection.py --action get_documents --collection-id <collection-id>
python inference.py --questionAnswer

在系統提示時輸入集合識別碼、文件識別碼和問題。

文件摘要

識別集合和文件，然後執行摘要範例：

python collection.py --action list
python collection.py --action get_documents --collection-id <collection-id>
python inference.py --summarize

在系統提示時輸入集合識別碼和文件識別碼。

內容搜尋

識別集合與文件，然後執行內容搜尋範例：

python collection.py --action list
python collection.py --action get_documents --collection-id <collection-id>
python inference.py --context-search

在系統提示時輸入集合識別碼、文件識別碼和搜尋文字。

屬性擷取

識別集合和文件，然後執行擷取範例：

python collection.py --action list
python collection.py --action get_documents --collection-id <collection-id>
python inference.py --extract

當系統提示時，輸入集合 ID、文件 ID、屬性名稱、擷取提示、資料類型和選擇性說明。 

繼續使用 API 建置

Python 示範提供的是有效的實作圖樣，而非完整的 API 文件。

使用開始使用 Knowledge Base API 以了解 API 資源模型、文件生命週期、推論行為與回應處理。

當您需要目前的端點路徑、參數、請求與回應方案，以及狀態資訊時，請使用 Knowledge Base API 參考。

疑難排解

示範會將詳細的診斷資訊寫入：

logs/knowledgebase-demo.log

記錄檔會記錄 DEBUG 層級資訊，而主控台則顯示 WARNING 層級及以上的訊息。

如果操作失敗：

• 審閱 logs/kinowledgebase-demo.log 以取得有關請求與驗證的詳細資訊。
• 確認config.yaml中的設定。
• 確認您使用的 PDF 存在且可存取。
• 確認應用程式正在為您的組織使用適當的服務端點。 
• 確認已驗證的身分擁有要求資源的存取權。
• 關於 API 失敗，請保留回應標頭中傳回的 X-Request-ID (如可用)。支援人員可以使用此識別碼來追蹤要求。 

實施考量

• 完整的工作流程接受 PDF 檔案。
• 示範會在設定 API 存取權後管理驗證權杖。
• API 操作使用已驗證身分可用的權限。
• 來源套件包含區域端點探索功能，但生產端點值應來自目前的 Knowledge Base API 文件，而非示範中所含的舊版值。