跳至主要内容
版本:PrivStation 2.6.0
Markdown 原文

API 串接 & API 列表

API 串接​

每一個 API 請求都必須包含有效的 API 金鑰。請在 Authorization 標頭中加入以下格式的金鑰

Authorization: Bearer <your-api-key>

PrivAI 支援兩種類型的 API Key:

  • Master Key:具有管理者權限,可跨租戶檢視與管理資料,也可呼叫 API Key 管理相關 API。

  • 租戶 Key / Tenant Key:提供給單一客戶或單一租戶使用,只能存取該 API Key 所屬租戶的資料。

備註:

  • 原本由系統環境變數設定的 SECRET_KEY 機制仍保留,並在此架構下作為 Master Key 使用。

  • Tenant Key 的呼叫方式與既有 API 完全相同,僅需將原本的金鑰替換為客戶專屬 API Key。

  • 當 API Key 已過期、被停用或格式不正確時,系統將拒絕請求並回傳對應錯誤碼。

API Key 類型與權限說明​

PrivAI 使用 API Key 作為身份驗證與資料範圍控制的基礎。不同類型的 API Key 對應不同的權限與資料可見範圍。

Key 類型說明

類型說明
Master Key系統管理用金鑰,可檢視所有租戶資料,並管理租戶Key
Tenant Key單一租戶專屬金鑰,只能存取自身租戶資料

權限差異

功能Master Key租戶 Key
呼叫既有 PrivAI API支援支援
檢視所有租戶資料支援不支援
建立 API Key支援不支援
查詢 API Key 列表支援不支援
更新 / 停用 / 啟用 API Key支援不支援
存取其他租戶資料支援不支援

使用說明

  • 使用 Master Key 呼叫既有 PrivAI API 時,系統將以管理者視角回傳跨租戶資料。

  • 使用 客戶 API Key 呼叫既有 PrivAI API 時,系統會自動套用該租戶的資料範圍限制(tenant scope)。

  • 客戶 API Key 無需額外理解租戶概念,也不需改變既有 API 呼叫方式。

伺服器主機​

測試 PrivAI 伺服器是否正常運作

curl -X 'GET' \
'http://127.0.0.1:8000/v1/models' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <your-api-key>'

Request Headers

KeyValue
Request MethodGET
acceptapplication/json
AuthorizationBearer <your-api-key>

Response Body

{
"object": "list",
"data": [
{
"id": "ace-1-3b-reasoning",
"object": "model",
"created": 1677610602,
"owned_by": "APMIC"
}
...
]
}

API 列表​

PrivAI 所有的 API 端點。

模型管理模組​

請求方法端點描述
GET/v1/models取得所有模型

API Key 管理模組​

請求方法端點描述
GET/v1/api-keys取得所有 API Key 列表
POST/v1/api-keys建立 API Key
PUT/v1/api-keys/{id}更新 / 停用 / 啟用 API Key

檔案管理模組​

請求方法端點描述
GET/v1/files取得所有檔案列表
POST/v1/files上傳檔案
POST/v1/files/{file_id}/parse單一檔案轉換
GET/v1/files/{file_id}取得單一檔案資料
GET/v1/files/{file_id}/content下載檔案
DELETE/v1/files/{file_id}刪除單一檔案

知識版本管理模組​

請求方法端點描述
GET/v1/filesets取得所有知識版本列表
POST/v1/filesets新增知識版本
GET/v1/filesets/{fileset_id}取得單一知識版本資料
GET/v1/filesets/{fileset_id}/files取得單一知識版本的檔案列表
PUT/v1/filesets/{fileset_id}更新知識版本
DELETE/v1/filesets/{fileset_id}刪除知識版本
POST/v1/filesets/{fileset_id}/commitcommit 知識版本
DELETE/v1/filesets/{fileset_id}/commit取消 commit 知識版本
POST/v1/filesets/{fileset_id}/duplicate複製知識版本
POST/v1/chat/references/{fileset_id}&{query}資料參考搜尋 (在指定的知識版本中,搜尋相關的參考資料)

提示詞管理模組​

請求方法端點描述
GET/v1/prompts取得所有提示詞列表
POST/v1/prompts新增提示詞
GET/v1/prompts/{prompt_id}取得單一提示詞資訊
DELETE/v1/prompts/{prompt_id}刪除提示詞
POST/v1/prompts/{prompt_id}/optimize/auto提示詞自動優化
POST/v1/prompts/{prompt_id}/optimize/instruct提示詞手動優化

對話模組​

請求方法端點描述
POST/v1/chat/completions與 LLM 互動

報告生成模組​

請求方法端點描述
POST/v1/report-generation/templates建立報告模板,並觸發 PDF 模板解析流程
GET/v1/report-generation/templates/{id}取得報告模板目前狀態與資料
POST/v1/report-generation/templates/{id}/confirm確認模板 slot 結構,並觸發撰寫指引生成
PATCH/v1/report-generation/templates/{id}更新已完成的報告模板內容

備註:

  • POST /v1/report-generation/templates 會建立報告模板,並非同步執行 PDF 解析、HTML 轉換與模板欄位抽取。

  • 建立後模板狀態會先進入 parsing_template。

  • 當 Template Extractor 完成後,模板狀態會轉為 pending_confirm,等待使用者確認或編輯 slot 結構。

  • 使用者確認 slot 結構後,可呼叫 POST /v1/report-generation/templates/{id}/confirm。

  • 呼叫 confirm API 後,系統會進入 generating_guidelines 狀態,並觸發 Outline Generator 產生撰寫指引及章節大綱。

  • 撰寫指引及大綱生成完成後,模板狀態會轉為 completed。

  • 若任一非同步流程失敗,模板狀態會轉為 failed。

  • 若建立模板時有提供 webhook_url,系統會在狀態變更時主動發送 callback。

其他工具​

請求方法端點描述
POST/v1/qa/generate問答集生成