配置AI日誌策略 - API Gateway

AI 網關在處理模型請求時會產生大量日誌資料。AI 日誌策略支援按需選擇日誌欄位、使用內建模板大量新增欄位、自訂日誌欄位及 JSON PATH 配置，從而控制日誌記錄範圍、降低儲存成本。此功能對已相容協議（如 OpenAI、百鍊）和自訂 HTTP 協議均適用，但兩者的配置能力有所差異。

前提條件

已開通阿里雲 API Gateway服務。
已建立 AI 網關執行個體。具體操作，請參見建立網關執行個體。
已配置至少一個 Model API 或 Agent API。具體操作，請參見管理Model API 和管理Agent API。

協議類型與配置能力

AI 網關根據 Model API 或 Agent API的協議類型提供不同的日誌策略配置能力：

能力	已相容協議（如 OpenAI、百鍊）	自訂 HTTP 協議
預定義基礎欄位	支援	不支援
內建模板大量新增	支援	支援
自訂 JSON PATH 欄位	支援	支援
欄位獨立啟用/禁用	支援	支援

每條 Model API 的路徑（ Path ）擁有獨立的欄位配置。不同路徑下，由於 API 請求或響應結構的不同，同一欄位的 JSON PATH 可能有所不同。

說明

已相容協議中支援預定義基礎欄位能力的協議與情境：

Model API：OpenAI和百鍊下的文本產生、圖片產生情境。
Agent API：百鍊應用。

啟用 AI 請求日誌

登入 API Gateway控制台。
在左側導覽列，單擊AI 网关 > 实例。
在 AI 網關頁面，單擊目標執行個體名稱，進入執行個體詳情頁。
單擊 Model API 頁簽，在 Model API 列表中單擊目標 Model API 名稱。
在 API 詳情頁，單擊策略与插件頁簽。
在预置策略与插件地區，找到AI 请求日志面板，開啟開關，單擊展開。
根據 Model API 的協議類型，配置日誌欄位：
- 已相容協議（如 OpenAI）：參見配置已相容協議的日誌欄位。
- 自訂 HTTP 協議：參見配置自訂 HTTP 協議的日誌欄位。
配置完成後，單擊保存。

配置已相容協議的日誌欄位

對於使用已相容協議（如 OpenAI）的 Model API，AI 請求日誌面板提供基礎欄位管理、模板大量新增和自訂欄位三項能力。

面板布局

地區	說明
啟用開關	控制 AI 請求日誌功能的開啟和關閉。
Path 列表	顯示當前 Model API 支援的所有路徑。選擇不同路徑時，右側欄位配置隨之切換。
基礎欄位	基礎欄位主要覆蓋對話、元資訊、用量、工具四個分類。
自訂欄位	手動添加的自訂日誌欄位。
操作按鈕	從模板大量新增：從內建支援模板中大量匯入欄位。添加自定义字段：手動添加欄位。

說明

Path 列表包含當前 API 支援的各個路徑，典型的 Path 如 OpenAI 相容的/v1/chat/completions、/v1/completions。在後端服務模型為多服務時，一個 Path 可能對應多條路由，同 Path 的多條路由對應使用同一份配置。
每個欄位可通過行首的開關控制項獨立啟用或禁用。表頭顯示當前啟用數量和總數，如 "基礎欄位 (14/24)"。單擊仅展示开启的字段可過濾僅顯示已啟用的欄位。

基礎欄位

主要的基礎欄位按分類組織如下：

分類	欄位樣本	說明
對話	question、answer	使用者提問和模型響應內容。
元資訊	request_model、model、chat_id	請求模型名稱、響應模型名稱、會話 ID。
用量	input_token、output_token、total_token、input_token_details、output_token_details、input_tokens_details.cached_tokens、output_tokens_details.reasoning_tokens	請求和響應的 Token 消耗量及明細。
工具	tool_use	工具調用資訊。

說明

欄位記錄位置：基礎欄位統一以固定的 Key（欄位名稱）寫入日誌。其中，除 answer、question外，其餘基礎欄位均作為一級欄位存放在 ai_log 欄位下，answer 與 question 已從ai_log中單獨抽取，作為獨立欄位存放。
系統內建欄位：model、chat_id、input_token、input_token_details、output_token、output_token_details、total_token 為系統內建欄位。系統內建欄位預設開啟，欄位提取時優先按已配置的 JSON PATH 進行提取，未配置時按系統內建規則進行預設提取。
流式與非流式欄位：多數響應欄位同時支援非流式響應和流式響應兩種提取方式，對應不同的 JSON PATH 配置。以 answer 欄位為例，在 /v1/chat/completions 路徑下，非流式響應的提取路徑為 choices.0.message.content，流式響應的提取路徑為 choices.0.delta.content。

JSON PATH 配置

JSON PATH 配置文法

JSON Path 配置採用 GJSON 文法，用於從 API 請求或響應的 JSON 資料中提取指定欄位值。

文法說明：

使用 . 訪問對象中的欄位
使用數組下標訪問數組元素，下標從 0 開始
支援多層嵌套訪問

例如，choices.0.message.content 表示：

先擷取 choices 數組
再取第 0 個元素
然後依次擷取其中的 message.content 欄位值

樣本：

以下為一個響應樣本：

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "我是阿里雲開發的一款超大規模語言模型，我叫千問。"
      },
      "finish_reason": "stop",
      "index": 0
    }
  ],
  "object": "chat.completion",
  "usage": {
    "prompt_tokens": 3019,
    "completion_tokens": 104,
    "total_tokens": 3123,
    "prompt_tokens_details": {
      "cached_tokens": 2048
    }
  },
  "model": "qwen-plus",
  "id": "chatcmpl-6ada9ed2-7f33-9de2-8bb0-78bd4035025a"
}

對應欄位的 JSON PATH 樣本：

欄位名稱	JSON PATH	提取結果
`answer`	`choices.0.message.content`	`我是阿里雲開發的一款超大規模語言模型，我叫千問。`
`model`	`model`	`qwen-plus`
`input_token`	`usage.prompt_tokens`	`3019`

不同路徑或來源下的 JSON PATH 差異

Model API 可能關聯多個路徑（如 /v1/chat/completions、/v1/completions、/v1/responses），不同路徑和來源下同一欄位的 JSON PATH 存在差異。以 question、answer、input_token 三個代表性欄位為例：

欄位	來源	`/v1/chat/completions`	`/v1/completions`	`/v1/responses`
question	請求	`messages.@reverse.#(role=="user").content`	`prompt`	`input`
answer	非流式響應	`choices.0.message.content`	`choices.0.text`	`output.#(type=="message").content.#(type=="output_text").text`
answer	流式響應	`choices.0.delta.content`	`choices.0.text`	`delta`
input_token	非流式響應	`usage.prompt_tokens`	`usage.prompt_tokens`	`usage.input_tokens`
input_token	流式響應	`usage.prompt_tokens`	`usage.prompt_tokens`	`response.usage.input_tokens`

說明

在 Path 列表中切換不同的路徑時，對應的基礎欄位 JSON PATH 會自動更新。修改某個路徑下的欄位配置不會影響其他路徑。
如需修改某個欄位的 JSON PATH，可在欄位所在行的操作列中單擊编辑，並在彈出的編輯對話方塊中修改對應的 JSON PATH 值。系統將根據配置的 JSON PATH，從 API 請求或響應中提取相應欄位。

通過內建模板大量新增欄位

AI 請求日誌提供內建模板，可大量新增預定義欄位。

在 AI 請求日誌面板，單擊“從模板大量新增”。
选择模板，然後勾選需要添加的欄位，單擊批量添加。

內建模板共 15 個，按供應商分為以下兩組：

OpenAI 模板（6 個）

情境	路徑
文本產生	`/v1/chat/completions`
	`/v1/completions`
	`/v1/responses`
圖片產生	`/v1/images/generations`
	`/v1/images/edits`
	`/v1/images/variations`

百鍊模板（9 個）

情境	路徑
文本產生	`/api/v1/services/aigc/text-generation/generation`
圖片產生	`/api/v1/services/aigc/text2image/image-synthesis`
	`/api/v1/services/aigc/image2image/image-synthesis`
	`/api/v1/services/aigc/image2image/out-painting`
	`/api/v1/services/aigc/virtualmodel/generation`
	`/api/v1/services/aigc/background-generation/generation`
	`/api/v1/services/aigc/multimodal-generation/generation`
	`/api/v1/tasks`
Agent應用	`/api/v1/apps/{app_id}/completion`

說明

內建模板提供的可選欄位數量顯著多於基礎欄位。以 OpenAI /v1/chat/completions 模板為例，可選欄位超過 200 個，並按照對話、配置、工具、用量、元資訊、候選、標識、緩衝、多模態、機率等類別進行組織，便於快速選擇和配置。
內建模板中的欄位配置可作為參考，實際欄位定義及含義請以對應協議的 API 文檔為準。

添加自訂欄位

除基礎欄位和模板欄位外，還可以手動添加自訂欄位。

在 AI 請求日誌面板，單擊添加自定义字段。

配置以下參數：

參數	說明
欄位名稱	自訂的欄位名稱，作為日誌中 `ai_log` 欄位下的 Key。
來源	欄位來源，可選：請求、非流式響應、流式響應。
Json Path	從對應來來源資料中提取欄位值的 JSON Path 路徑。
描述	欄位的用途說明。

單擊確認按鈕完成配置。

自訂欄位添加後，顯示在自定义字段標籤頁。可通過操作列的编辑和删除管理已有欄位。

配置自訂 HTTP 協議的日誌欄位

對於使用自訂 HTTP 協議的 Model API，AI 請求日誌不提供帶有預定義 JSON Path 的基礎欄位。需要根據實際規則，自行配置需要記錄的欄位，並可通過手動添加欄位或從模板匯入欄位的方式完成配置。

配置方式如下：

在 AI 請求日誌面板，根據實際協議的請求和響應結構，通過添加自定义字段定義需要記錄的欄位。
為每個欄位指定正確的 JSON PATH，確保路徑與實際資料結構匹配。
也可以使用模板匯入相近協議的模板作為基礎，再根據實際協議結構調整 JSON PATH。

配置樣本

樣本一：記錄 OpenAI 相容協議的核心日誌欄位

以下樣本展示如何在/v1/chat/completions路徑下記錄非流式對話內容和 Token 用量，以減少日誌大小。

進入目標 Model API 的策略与插件頁簽，展開 AI 请求日志面板。
選擇 /v1/chat/completions 路徑。

在基础字段標籤頁，啟用以下欄位：

欄位名稱	來源	分類	用途	預設啟用
question	請求	對話	記錄使用者提問內容	否
answer	非流式響應	對話	記錄非流式響應中模型的回答內容	否
input_token	非流式響應	用量	記錄輸入 Token 數	是
output_token	非流式響應	用量	記錄輸出 Token 數	是
total_token	非流式響應	用量	記錄 Token 總數	是

單擊保存。

樣本二：使用模板大量新增百鍊欄位

以下樣本展示如何通過內建模板快速添加百鍊文本產生協議的日誌欄位。

進入目標 Model API 的策略与插件頁簽，展開 AI 请求日志面板。
單擊從模板大量新增。
选择模板為/api/v1/services/aigc/text-generation/generation。
勾選需要的欄位，單擊批量添加。
根據實際需求，在欄位列表中啟用或禁用特定欄位，或修改其Json Path。
單擊保存。