API 整合提供了一個 OpenAI 兼容的聊天完成端點，您可以用它來與您的 Pathors 專案進行互動。
聊天完成
路徑參數
請求頭
使用您的 API 金鑰進行 Bearer 令牌認證
會話 ID，用於對話連續性。強烈建議使用此標頭傳遞會話 ID，而不是請求體中的
session_id 參數。
請求體
對話中的訊息陣列。每條訊息都應該有一個 role（“system”、“user” 或
“assistant”）和 content。
(deprecated) 會話 ID，用於對話連續性。建議使用 X-Session-ID
標頭代替。僅在不支持自訂標頭的環境中使用此參數。
可供助手使用的外部工具定義陣列。每個工具應該有一個 type（目前僅支持 “function”）和一個包含 name、description 和 parameters（JSON Schema 格式）的 function 物件。
{
"messages": [
{
"role": "user",
"content": "你好！"
}
],
"stream": false
}
{
"messages": [
{
"role": "user",
"content": "舊金山的天氣怎麼樣？"
}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "獲取當前天氣資訊",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "城市名稱"
}
},
"required": ["location"]
}
}
}
]
}
回應頭
對話的會話 ID。此頭部會在回應中返回，可用於後續請求。
choices[].message.tool_calls
助手進行的工具調用陣列（當提供並使用工具時）
完成終止的原因。正常完成時為 “stop”，調用工具時為 “tool_calls”。
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1677858242,
"model": "pathway-default",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "你好！我能幫你什麼忙？"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": -1,
"completion_tokens": -1,
"total_tokens": -1
},
"session_id": "session-xyz789"
}
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1677858242,
"model": "pathway-default",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "",
"tool_calls": [
{
"id": "call_123",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"location\": \"舊金山\"}"
}
}
]
},
"finish_reason": "tool_calls"
}
],
"usage": {
"prompt_tokens": -1,
"completion_tokens": -1,
"total_tokens": -1
},
"session_id": "session-xyz789"
}
流式回應
當 stream 設置為 true 時，回應將以伺服器發送事件（SSE）的形式流式傳輸。每個事件包含以下格式的回應塊：
{
"id": "chatcmpl-abc123",
"object": "chat.completion.chunk",
"created": 1677858242,
"model": "pathway-default",
"choices": [
{
"index": 0,
"delta": {
"content": "你好"
},
"finish_reason": null
}
],
"session_id": "session-xyz789"
}
finish_reason: "stop"，並跟隨 data: [DONE]。
錯誤回應
| 狀態碼 | 描述 |
|---|
| 400 | 無效的請求體 |
| 401 | 無效的認證 |
| 500 | 內部伺服器錯誤 |
使用工具
當您在請求中提供工具時，助手可以在對話中調用它們。在收到帶有 tool_calls 的回應後，您應該：
- 使用提供的參數執行請求的工具
- 在後續請求中以 “tool” 角色訊息發送工具結果
- 助手然後將使用工具結果來製定其最終回應
工具訊息格式
收到工具調用後，發送結果：
{
"messages": [
{"role": "user", "content": "天氣怎麼樣？"},
{
"role": "assistant",
"content": "",
"tool_calls": [
{
"id": "call_123",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"location\": \"舊金山\"}"
}
}
]
},
{
"role": "tool",
"content": "22°C，晴朗",
"tool_call_id": "call_123",
"name": "get_weather"
}
],
"session_id": "existing_session_id"
}
設置指南
- 在您的 Pathors 專案設置中啟用 API 整合
- 在您專案的整合設置中生成 API 金鑰
- 在您的請求中使用 API 金鑰作為 Authorization 頭部
- （可選）使用會話 API建立會話以維持對話連續性
- （可選）定義並提供工具以擴展功能
