大多數 LLM 可觀測性問題不是工具問題，而是 schema 問題。能快速定位故障、有把握地歸屬成本、從容回答審計問題的團隊，並沒有在記錄一切。他們在穩定地記錄那關鍵的一小撮欄位，並且劃了一條硬底線：金鑰和客戶內容永遠不進日誌。本文講這份欄位清單、必須擋在日誌之外的東西，以及 LLM API 資料保留中朝兩個方向都讓人意外的部分：廠商保留的東西不是你的審計軌跡，而你保留的東西需要是有意為之的，因為相關控制確實存在，但它們不是預設開啟的。本站的運維類文章已經連著幾週在引用日誌；這一篇講的就是日誌本身。
LLM API 日誌：四個用途，一套 schema
一條有用的 LLM API 呼叫日誌同時服務四個用途，你需要的欄位直接對應到它們。
除錯。HTTP 狀態碼；響應體中的錯誤type型別與message錯誤碼；存在時的錯誤code訊息欄位；請求 ID；這個邏輯請求的重試次數；以及耗時。有了這些，一次失敗就不再是一個故事，而是一條記錄：嘗試了什麼、返回了什麼、在重試序列的哪一步死掉的。
歸屬。實際使用的 model ID、端點，以及呼叫方身份：是哪個功能、哪個團隊或哪個客戶發起的呼叫。如果廠商在響應頭裡暴露了組織或 workspace 標識，也把它們記下來，因為它們讓你能用自己的記錄去和廠商的檢視對賬。API 用量歸屬日誌是發票上的一個行項與產生它的程式碼路徑之間的連線組織。值得打的標籤維度，以及按這些維度分組為什麼划算，見用量歸屬指南。
成本。每個響應的用量usage物件裡的 token 計數，以及能說明快取讀取是否真的發生了的快取相關欄位。把這些欄位記下來，成本復盤就從考古變成一次查詢；其中的機制以及能證明快取命中的欄位，見快取指南。
穩定性。回答“它是不是在變差”的計數器：按時間變化的限流響應、服務端錯誤響應、重試預算耗盡，以及實際應用的退避時長。這些指標是重試紀律在可觀測性上的另一半，紀律本身見限流指南。
一套 schema，四個消費者。實用的技巧是每個邏輯請求（而不是每次底層嘗試）寫一條結構化日誌，把上面所有內容都補進去，這樣同一條記錄既服務於值班工程師，也服務於財務的表格和審計員。
請求 ID：你排查 API 問題的錨點
如果你在 token 計數之外只記一個欄位，那就記請求 ID。Anthropic 的錯誤文件對這一點說得很明確：每個 API 響應都包含一個唯一的request-id響應頭，同一個標識也會作為錯誤響應體裡的request_id欄位出現，而且當你就某個具體請求聯絡支援時，你要提供這個 ID。最後這點才是關鍵。關於間歇性故障的支援對話，如果沒有一個雙方都能查詢的標識，永遠不會有進展；有了它，對話就變成一次查詢。
以程式設計方式讀取它很直接，但各 SDK 不同。Python 和 TypeScript SDK 把它暴露為頂層響應物件上的_request_id屬性；C#、Go、Java 和 PHP SDK 通過各自的原始響應訪問器暴露它，Ruby 則通過中介軟體。要讀取其他響應頭，比如anthropic-organization-id前面提到的這些，anthropic-workspace-id在所有 SDK 裡都用同樣的原始響應訪問器（Ruby 裡用同一個中介軟體）。在 Claude Platform on AWS 上，響應會帶兩個 ID：AWS 請求 ID，x-amzn-requestid它在 CloudTrail 中有索引，是查 CloudTrail 時要用的那個；另一個是 Anthropic 請求 ID，用於提交支援工單。如果你跑在那個環境裡，兩個都記；它們回答的是不同的問題。這條通用原則早於任何廠商存在：請求 ID 加錯誤碼，就是把一次失敗釘到一次呼叫上的那一對，而這正是錯誤碼指南在分診時假定你已經擁有的東西。
永遠不進日誌的內容
兩類，沒有任何值得破例的情形。第一類是憑證：API key、bearer token 和認證頭，永遠不該出現在日誌輸出裡，任何級別都不行，包括 debug。這一點值得直說，因為洩露路徑都很無聊：一個過於勤快的請求日誌器列印了請求頭，一個錯誤處理器把整個請求物件序列化了，一張支援工單裡有人貼上了配置。同樣的紀律在 CI 流水線和應用日誌裡完全適用。
第二類是原始客戶內容：完整的 prompt 和補全結果，尤其是當它們包含個人資料或受監管資料時。這條線更難守，因為原始內容對除錯確實有用。替代工具箱：記錄長度和雜湊而不是正文；需要感受資料形態時，記錄分類標籤或脫敏樣本；如果監管要求強制保留內容，就單獨建一個受訪問控制的儲存，並配自己的保留計時器。一個可行的模式是三段式過濾：一份允許記錄的欄位名白名單；寫入前的一遍清洗，丟棄任何匹配憑證形態的內容並在命中時告警；以及對日誌儲存本身的訪問控制和保留期限。告警很重要；如果某種金鑰形態出現在了日誌流裡，你希望幾分鐘內就知道，而不是等到下次審計。
LLM API 資料保留：廠商保留了什麼
這裡就是很多團隊會朝一個方向誤解的部分。廠商側確實存在日誌，而且預設不由你控制。OpenAI 的資料管控文件把兩半都說得很清楚。
讓人安心的一半：自 2023 年 3 月 1 日起，傳送到 OpenAI API 的資料不會被用於訓練或改進 OpenAI 的模型，除非客戶明確選擇加入資料共享。
運維意義上的另一半：API 用量會生成濫用監控日誌，用於執行使用政策，這些日誌可能包含客戶內容，例如 prompt 和響應，以及派生後設資料，例如分類器輸出。預設情況下這些日誌最多保留 30 天，除非法律要求更長保留期，或者為保護服務或第三方有合理必要。符合條件的客戶可以通過獲批零資料保留或修改版濫用監控，讓客戶內容不被寫入這些日誌，兩者都需要事先批准並滿足額外要求。對你架構的結論很直白：廠商的保留不是你的審計軌跡。如果你需要記錄發生了什麼、什麼時候、花了多少、由誰呼叫，這些後設資料得你自己留。
也不要朝另一個方向過度糾正。“不用於訓練”不等於“什麼都不保留”，而 30 天這個數字是某一類特定日誌有文件依據的保留視窗，並不是承諾說 30 天后每個請求的每一絲痕跡都不可恢復。你的內部策略要對著真實的控制項來寫，同一份文件按端點詳細說明了這些控制項。
兩個常被誤讀的保留控制項
那份文件裡有兩個細節值得牢記，因為它們會打破假設。
第一，零資料保留改變的是行為，不只是策略：啟用之後，storeResponses 和 Chat Completions 端點的 store 引數總是被當作關閉處理false，即使請求試圖把它設為開啟true。所以一個假設“我設了 store=true，因此這段對話可以取回”的應用，在 ZDR 下就是錯的，而且失敗是靜默的，因為請求會成功。如果你的產品依賴已儲存的狀態，就去按你組織實際的資料策略核實端點行為，而不是假設你的引數會生效。
第二，Responses API 預設有 30 天的應用狀態保留期，當相關引數store被設為需要保留的取值時同樣如此true；在這些情況下，響應資料至少會儲存 30 天。把該端點當作無狀態的團隊會在兩個方向上都被驚到：他們以為已經消失的資料其實被保留了，他們以為會保留的資料則受策略依賴的行為支配。同一個頁面按端點列出了保留情況，包括哪些端點有資格使用更嚴格的控制項，還指出資料駐留是專案級配置選項、受資格限制，且定價可能與標準端點不同。這兩點都要對照當前頁面和你的賬號來確認，而不是對照一篇部落格文章，包括這一篇。
把日誌與保留當作採購維度
一旦你把日誌看成一個能力面，它就屬於供應商選型，而不屬於合同細則。評估時有四個值得問的問題：你能不能取回任意單次呼叫（包括失敗的呼叫）的請求 ID；你能不能從響應裡讀到組織和 workspace 標識，讓歸屬可被證明；保留姿態能否配置到你的合規團隊需要的程度，審批又需要什麼；以及資料在哪裡處理和儲存，如果駐留對你重要的話。這些問題會直接嵌進聚合訪問與直連的對比裡的架構權衡，因為中間層會改變誰持有日誌、你能看到哪些標識。你所執行平臺的端點級細節都在它自己的文件裡。
欄位地圖
本站的運維繫列已經長成一組文章，每一篇都依賴同一套可觀測性底座。下面是它們與本套 schema 中欄位的對應關係：
| 文章 | 它需要你日誌裡的什麼 |
| :- | :- |
| 用量與成本歸屬 | token 計數、模型、呼叫方標籤、組織與 workspace 標識 |
| 錯誤碼分診 | 狀態碼、錯誤型別與錯誤碼、請求 ID |
| prompt 快取 | 快取讀取與寫入的 token 欄位，用來證明命中 |
| CI 整合 | 金鑰衛生：憑證完全不出現在日誌裡 |
| 限流與重試 | 限流與錯誤計數器、退避與預算指標 |
實施檢查清單
- 定義白名單 schema：每個被記錄欄位的名稱、型別和可空性，並在功能變化時複核它。
- 在每次呼叫上抓取請求 ID 和錯誤碼，並把它們作為一等欄位儲存，而不是塞在一條 message 字串裡。
- 按邏輯請求把用量 token 欄位和快取欄位記錄為結構化數字。
- 給每次呼叫打上功能、團隊和客戶標識，並用廠商的響應頭核對這些標籤。
- 寫入前過濾：丟棄形似憑證的字串和已知的 PII 模式，並在過濾器命中時告警。
- 把除錯日誌與審計記錄分開，兩者使用不同的保留視窗。
- 限制誰能讀取日誌儲存，並記錄對它的訪問。
- 每季度對照廠商當前文件重新審計 schema，因為端點和保留控制都會變。
這些也都不光鮮，但它決定了一個技術棧是你能運營的，還是你只能寄希望於它的。日誌就是做出這個選擇的地方，一次一個 schema 決策。