Chat Completions

POST /v1/chat/completions

與 OpenAI Chat Completions API 100% 相容，並透過 vecstruct 擴充欄位支援 RAG、Memory 等功能。

請求 Headers

POST /v1/chat/completions
Authorization: Bearer sk-your-api-key
Content-Type: application/json

請求 Body

{
  "model": "openai/gpt-4o",
  "messages": [
    { "role": "system", "content": "你是一位技術助理，根據知識庫內容回答問題" },
    { "role": "user", "content": "API 認證要怎麼設定？" }
  ],
  "temperature": 0.7,
  "max_tokens": 1024,
  "stream": false,
  "vecstruct": {
    "project_id": "019373a01a2b7c3d4e5f6a7b8c9d0e1f",
    "rag": true,
    "rag_top_k": 5,
    "use_memory": true,
    "metadata": {
      "user_id": "user-123"
    }
  }
}

請求欄位

標準 OpenAI 欄位：

欄位	類型	必填	說明
`model`	string	✓	模型 ID，格式為 `provider/model-name`
`messages`	array	✓	對話訊息列表
`temperature`	number		生成溫度 0-2，預設 `0.7`
`max_tokens`	number		最大輸出 Token 數；提供時會轉送給 Provider，未提供則不設定
`stream`	boolean		是否串流回應，預設 `false`
`top_p`	number		Nucleus sampling，預設 `1`
`frequency_penalty`	number		頻率懲罰，-2 到 2，預設 `0`
`presence_penalty`	number		存在懲罰，-2 到 2，預設 `0`
`stop`	string / string[]		停止序列

vecstruct 擴充欄位：

欄位	類型	預設值	說明
`project_id`	string	API Key 綁定的知識庫	指定注入哪個知識庫
`rag`	boolean	`true`（Key 有綁知識庫時）	是否啟用 RAG 注入
`rag_top_k`	integer	方案預設值	覆蓋知識庫設定的 Top-K
`use_memory`	boolean	`false`	是否注入 Memory 記憶
`metadata`	object	`null`	稽核自訂標記（flat JSON，詳見下方說明）

RAG 控制優先順序（從高到低）

vecstruct.rag = false → 關閉 RAG
vecstruct.project_id 指定 → 使用指定知識庫
API Key 綁定的知識庫 → 靜態預設
無任何設定 → 純 AI Gateway，不注入 RAG

metadata 規格：

結構：單層 flat JSON（不允許巢狀 object 或 array）
整體大小：≤ 16 KB；Key 數量：≤ 50 組
Key 格式：^[a-zA-Z0-9_]+$；Value 型別：string、number、boolean
metadata 會原樣寫入 Audit Log，供關聯工單 ID、用戶 ID 等自訂追蹤資訊

回應範例（非串流）

{
  "id": "chatcmpl-id",
  "object": "chat.completion",
  "created": 1746700000,
  "model": "openai/gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Docker 利用 Linux 容器技術（namespace + cgroup）將應用與物理機隔離，啟動速度更快，資源占用更少…"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 120,
    "completion_tokens": 80,
    "total_tokens": 200
  },
  "vecstruct": {
    "audit_id": "019cdad6340575609cda639e439c1015",
    "rag_sources": [
      {
        "document_id": "019373a01a2b7c3d4e5f6a7b8c9d0e1f",
        "title": "container-fundamentals.md",
        "chunk": "Docker 基於 Linux namespace + cgroup…",
        "similarity": 0.92
      }
    ],
    "memory_used": true,
    "credits_consumed": 0.05,
    "balance_consumed_usd": 0.000240
  }
}

vecstruct 回應欄位：

欄位	類型	說明
`audit_id`	string	此次請求的 Audit Log ID
`rag_sources`	array	RAG 引用的段落列表
`memory_used`	boolean	是否有注入 Memory
`credits_consumed`	number	消耗的 Credits（RAG/Memory 功能）
`balance_consumed_usd`	number	消耗的 USD 餘額（LLM Token）

串流回應

當 stream: true 時，使用 Server-Sent Events（SSE）回傳：

data: {"id":"chatcmpl-id","object":"chat.completion.chunk","choices":[{"delta":{"content":"Docker"},"index":0}]}

data: {"id":"chatcmpl-id","object":"chat.completion.chunk","choices":[{"delta":{"content":"利用"},"index":0}]}

event: vecstruct
data: {"audit_id":"019cdad6340575609cda639e439c1015","rag_sources":[...],"memory_used":true,"credits_consumed":0.05,"balance_consumed_usd":0.000240}

data: [DONE]

串流結束前會有一個 event: vecstruct 的特殊事件，包含 RAG 來源、Credits 用量等 metadata。

模型格式

模型 ID 的格式為 provider/model-name，例如：

Provider	範例
`openai`	`openai/gpt-4o`, `openai/gpt-4o-mini`
`anthropic`	`anthropic/claude-3-5-sonnet`
`google`	`google/gemini-2.0-flash`
`baai`	`baai/bge-m3`（Embedding）
`cohere`	`cohere/rerank-v3.5`（Rerank）

完整的可用模型列表請參考 GET /v1/models。

錯誤碼

錯誤碼	HTTP	說明
1511	404	模型不存在
1512	400	模型未啟用
1002	400	請求格式錯誤（缺少 `model`、`messages` 格式不符）
1003	400	`metadata` 格式不符規格
1502	402	Credits 不足（RAG / Memory）
1506	403	目前方案不允許使用此模型
1508	402	USD 餘額不足（LLM Token）
1007	429	超過速率限制
2400	402	預算上限已達（啟用 Budget Cap 且 `action` 為 `block` 時觸發）

POST /v1/chat/completions​

請求 Headers​

請求 Body​

請求欄位​

回應範例（非串流）​

串流回應​

模型格式​

錯誤碼​