先看一個(gè)真實(shí)場景上周你的 LLM 功能還好好的用戶問題、返回格式、解析邏輯都沒動(dòng)過但這周一你發(fā)現(xiàn)線上開始偶發(fā)返回異常失敗率從 0.1% 漲到了 3%。代碼沒有合入任何變更模型服務(wù)也顯示健康可行為就是變了。這種讓人頭疼的問題往往不是 bug而是 LLM 在生產(chǎn)代碼庫里悄悄漂移了。本文會(huì)從工程視角拆解 LLM 漂移drift的本質(zhì)然后給出一套可以落地的穩(wěn)定化方案從版本鎖定、結(jié)構(gòu)化輸出、緩存與降級(jí)到評(píng)估回歸、監(jiān)控告警、CI 集成。無論你是剛接觸 LLM 應(yīng)用開發(fā)還是已經(jīng)在生產(chǎn)環(huán)境維護(hù) AI 功能都能照著這套思路把代碼重新收斂回可控狀態(tài)。1. 背景與核心概念1.1 什么是 LLM 漂移LLM 漂移指的是在沒有我們主動(dòng)修改代碼、提示詞或業(yè)務(wù)規(guī)則的情況下LLM 系統(tǒng)的輸出行為與之前不一致。這種不一致可能是輸出格式變化、語義偏差、回答長度變化甚至是拒絕回答策略變化。傳統(tǒng)軟件里“代碼不變則行為不變”是一條基本定律。但 LLM 應(yīng)用打破了這條定律因?yàn)橄到y(tǒng)的行為不僅由你的代碼決定還取決于遠(yuǎn)端模型服務(wù)的行為而遠(yuǎn)端模型并不完全受你控制。你可以把 LLM 漂移理解成一種“外部依賴漂移”。它與依賴庫版本升級(jí)帶來的行為變化類似但更難感知因?yàn)槟Ｐ头?wù)方不會(huì)在每次調(diào)整模型權(quán)重時(shí)都發(fā)布公告。即使是同一個(gè)模型 ID在不同時(shí)間段也可能有靜默的行為變化。輸出是非確定性的即便采樣參數(shù)完全一致也可能有微小差異。生產(chǎn)環(huán)境通常缺少對(duì)單次輸出質(zhì)量的自動(dòng)判斷能力。1.2 漂移的常見類型我把生產(chǎn)環(huán)境里常見的漂移分為四類方便后續(xù)排查時(shí)對(duì)號(hào)入座類型表現(xiàn)典型原因提示詞漂移同樣的 prompt 在不同時(shí)間產(chǎn)出不同格式prompt 模板被隱式修改、上下文長度變化模型漂移模型輸出風(fēng)格、長度、概率分布變化遠(yuǎn)端模型更新、服務(wù)方調(diào)整權(quán)重或溫度策略上下文漂移檢索到的上下文變化導(dǎo)致回答漂移RAG 知識(shí)庫更新、Embedding 模型更換、切分邏輯變更評(píng)估漂移相同測試集上評(píng)分持續(xù)上漲或下跌評(píng)分模型變化、評(píng)估標(biāo)準(zhǔn)理解偏差、過擬合評(píng)估集在真實(shí)項(xiàng)目中這四類漂移經(jīng)常疊加出現(xiàn)。比如你升級(jí)了 Embedding 模型檢索結(jié)果變化再疊加遠(yuǎn)端大模型更新最終用戶感受到的答復(fù)質(zhì)量就可能驟降。1.3 為什么生產(chǎn)代碼庫必須重視漂移生產(chǎn)代碼庫和實(shí)驗(yàn)?zāi)_本的最大區(qū)別在于有用戶、有流量、有可用性要求。實(shí)驗(yàn)階段你可以接受“某次輸出不好看”但生產(chǎn)環(huán)境一次批量回復(fù)質(zhì)量下降可能直接影響轉(zhuǎn)化率、客服效率甚至造成合規(guī)風(fēng)險(xiǎn)。更重要的是漂移會(huì)破壞你對(duì)系統(tǒng)的信任。如果每次發(fā)布前無法判斷模型行為是否回歸那么任何功能迭代都會(huì)變得很不可靠。反過來說只要建立了對(duì)抗漂移的工程機(jī)制LLM 應(yīng)用就可以像普通后端服務(wù)一樣做版本管理、回歸測試和監(jiān)控告警。2. 環(huán)境準(zhǔn)備與版本說明本文示例以 Python 環(huán)境為主因?yàn)?LLM 生態(tài)目前最成熟的 SDK 和工具鏈基本都在 Python 側(cè)。版本需要根據(jù)你的項(xiàng)目實(shí)際情況調(diào)整下面給出一套常見組合。2.1 運(yùn)行環(huán)境# 操作系統(tǒng) Ubuntu 22.04 / macOS 14 / Windows WSL2 # Python Python 3.10 # 建議使用虛擬環(huán)境 python -m venv .venv source .venv/bin/activate2.2 依賴說明# LLM SDK以 OpenAI 兼容接口為例 pip install openai # 配置與管理 pip install pydantic pydantic-settings # 測試與評(píng)估 pip install pytest pytest-asyncio # 緩存 pip install redis # 日志 pip install structlog # HTTP 客戶端 pip install httpx這里要強(qiáng)調(diào)一點(diǎn)不同 SDK 的 API 差異較大OpenAI 兼容接口是目前大多數(shù)云廠商和自建網(wǎng)關(guān)都會(huì)支持的標(biāo)準(zhǔn)。如果你使用的是其他廠商 SDK核心思路完全一致只需要替換客戶端初始化方式。2.3 目錄結(jié)構(gòu)llm_production_stable/ ├── src/ │ └── llm_gateway/ │ ├── __init__.py │ ├── client.py # LLM 客戶端封裝 │ ├── schema.py # 結(jié)構(gòu)化輸出 Schema │ ├── cache.py # 緩存層 │ ├── fallback.py # 降級(jí)與重試 │ └── monitor.py # 日志與監(jiān)控 ├── tests/ │ ├── test_schema.py │ └── test_client.py ├── evaluate/ │ ├── golden_set.jsonl # 金標(biāo)數(shù)據(jù)集 │ └── run_evaluation.py # 回歸評(píng)估腳本 ├── prompts/ │ └── intent.py # prompt 模板強(qiáng)制版本化 ├── .github/ │ └── workflows/ │ └── evaluate.yml # CI 評(píng)估流水線 └── pyproject.toml3. 核心機(jī)制為什么 LLM 會(huì)漂移以及如何對(duì)抗它3.1 模型是“外部依賴”不是穩(wěn)定函數(shù)很多開發(fā)者第一次寫 LLM 代碼時(shí)會(huì)把模型調(diào)用當(dāng)作普通函數(shù)response openai.chat.completions.create( modelgpt-4o-mini, messages[...], )這種寫法在實(shí)驗(yàn)階段沒問題但它隱含了一個(gè)假設(shè)同一段輸入、同一個(gè)模型 ID輸出總是可預(yù)期的。實(shí)際上并不成立。遠(yuǎn)端模型服務(wù)的權(quán)重、推理配置、部署實(shí)例都可能變化所以我們必須把模型調(diào)用當(dāng)成“不穩(wěn)定外部依賴”來設(shè)計(jì)系統(tǒng)。對(duì)抗思路也很簡單假設(shè)它不穩(wěn)定然后在外面加一層穩(wěn)定邊界。3.2 三個(gè)關(guān)鍵穩(wěn)定邊界第一個(gè)邊界是版本鎖定。把模型 ID、prompt 版本、輸出 schema 版本一起作為調(diào)用參數(shù)傳入并且在日志里記錄這樣一旦出現(xiàn)問題能立刻定位是哪一層變化導(dǎo)致。第二個(gè)邊界是結(jié)構(gòu)約束。無論模型返回什么自由文本業(yè)務(wù)層只消費(fèi)結(jié)構(gòu)化字段。解析失敗時(shí)寧可拋異常也不要讓一段臟字符串流向下游。第三個(gè)邊界是評(píng)估回歸。建立一套只覆蓋核心場景的金標(biāo)測試集每次發(fā)布前自動(dòng)跑分評(píng)分低于閾值則阻斷發(fā)布。3.3 成本、延遲與漂移的關(guān)系很多人以為為了對(duì)抗漂移就要做復(fù)雜鏈路實(shí)際上一個(gè)好的設(shè)計(jì)反而會(huì)降低成本。緩存在這里很關(guān)鍵對(duì)確定性要求高的請(qǐng)求命中緩存后直接返回完全繞開模型天然不受模型漂移影響。此外緩存還能降低延遲和費(fèi)用。但緩存也會(huì)帶來一個(gè)新問題如果模型行為已經(jīng)漂移而緩存一直沒有失效用戶會(huì)一直拿到“舊版結(jié)果”。所以緩存鍵里必須帶上 prompt 版本、業(yè)務(wù)參數(shù)版本、模型 ID必要時(shí)還要設(shè)置 TTL。4. 完整實(shí)戰(zhàn)案例構(gòu)建穩(wěn)定的 LLM 接入層下面我們從零開始搭建一個(gè)生產(chǎn)可用的 LLM 接入層。這個(gè)接入層的目標(biāo)非常明確讓業(yè)務(wù)代碼依賴一個(gè)穩(wěn)定的調(diào)用接口而不是直接依賴模型 SDK。4.1 定義結(jié)構(gòu)化輸出 Schema首先定義業(yè)務(wù)需要的輸出結(jié)構(gòu)。這里以“用戶意圖分類”為例適合用短文本演示但思路完全適用于摘要、信息抽取、客服回復(fù)生成等復(fù)雜場景。# 文件路徑src/llm_gateway/schema.py from enum import Enum from typing import Literal, Optional from pydantic import BaseModel, Field, field_validator class IntentType(str, Enum): AFTER_SALE aftersale PRE_SALE presale COMPLAINT complaint OTHER other class IntentResult(BaseModel): intent: IntentType confidence: float Field(ge0.0, le1.0, description置信度0-1) product_keyword: Optional[str] Field( defaultNone, description商品關(guān)鍵字僅在識(shí)別到商品時(shí)填寫 ) raw_reply_short: str Field(description給用戶的一句話簡短回復(fù)) field_validator(confidence) classmethod def validate_confidence(cls, v: float) - float: if v 0.6: # 低置信度時(shí)讓業(yè)務(wù)走人工兜底而不是強(qiáng)行走自動(dòng)流程 raise ValueError(confidence too low, please reply with can_not_handleTrue) return v class IntentResponse(BaseModel): can_not_handle: bool Field( description當(dāng)無法用給定商品/規(guī)則處理時(shí)設(shè)為 true ) result: Optional[IntentResult] None這里有幾個(gè)值得注意的設(shè)計(jì)點(diǎn)can_not_handle字段用于讓模型表達(dá)“我處理不了”業(yè)務(wù)層看到后直接轉(zhuǎn)人工避免模型硬答。置信度低于 0.6 時(shí)觸發(fā)校驗(yàn)異常防止低質(zhì)量結(jié)果進(jìn)入業(yè)務(wù)鏈路。輸出結(jié)構(gòu)必須可序列化、可校驗(yàn)后續(xù)評(píng)估和日志都依賴它。4.2 編寫帶版本控制的 Prompt 模板Prompt 不能散寫在代碼里要單獨(dú)管理并帶版本號(hào)。版本號(hào)會(huì)進(jìn)入緩存鍵和日志是排查漂移的關(guān)鍵線索。# 文件路徑prompts/intent.py from typing import Any PROMPT_VERSION intent-v3 def build_intent_messages(user_input: str, rules: list[str]) - list[dict[str, str]]: system_prompt f 你是一個(gè)電商客服意圖識(shí)別助手。 請(qǐng)嚴(yán)格根據(jù)用戶輸入和業(yè)務(wù)規(guī)則輸出 JSON。 要求 1. 只輸出 JSON不要輸出 Markdown。 2. JSON 必須符合以下結(jié)構(gòu) {{ can_not_handle: true/false, result: {{ intent: aftersale|presale|complaint|other, confidence: 0-1, product_keyword: string or null, raw_reply_short: 不超過20字的中文回復(fù) }} }} 3. 當(dāng)規(guī)則無法覆蓋用戶需求時(shí)設(shè)置 can_not_handletrue。 4. 當(dāng)置信度不足0.6時(shí)設(shè)置 can_not_handletrue。 業(yè)務(wù)規(guī)則 {chr(10).join(- rule for rule in rules)} 用戶輸入 {user_input} return [ {role: system, content: system_prompt}, {role: user, content: user_input}, ]把 prompt 版本號(hào)放在模板文件里而不是由業(yè)務(wù)方亂傳能有效避免“有人偷偷改了 prompt 但沒人記得”的問題。后續(xù)如果調(diào)整了 prompt 內(nèi)容請(qǐng)同步更新PROMPT_VERSION。4.3 封裝 LLM 客戶端接下來是核心的客戶端封裝。這一步要承擔(dān)幾件事統(tǒng)一模型 ID 和 provider 配置。固定采樣參數(shù)temperature0、top_p1.0。記錄完整調(diào)用信息。解析和校驗(yàn)結(jié)構(gòu)化輸出。失敗時(shí)拋出統(tǒng)一異常。# 文件路徑src/llm_gateway/client.py import json import time from typing import Any import httpx from pydantic import ValidationError from .schema import IntentResponse from .monitor import log_llm_call class LLMClientError(Exception): 統(tǒng)一 LLM 調(diào)用異常 class LLMClient: def __init__( self, api_base: str, api_key: str, model: str gpt-4o-mini, timeout_seconds: float 15.0, ): self.api_base api_base.rstrip(/) self.api_key api_key self.model model self.timeout_seconds timeout_seconds async def chat_json( self, messages: list[dict[str, str]], response_model: type[IntentResponse], prompt_version: str, temperature: float 0.0, ) - IntentResponse: start time.perf_counter() try: payload { model: self.model, messages: messages, temperature: temperature, top_p: 1.0, response_format: {type: json_object}, } async with httpx.AsyncClient(timeoutself.timeout_seconds) as client: resp await client.post( f{self.api_base}/chat/completions, headers{ Authorization: fBearer {self.api_key}, Content-Type: application/json, }, jsonpayload, ) resp.raise_for_status() data resp.json() content data[choices][0][message][content] # 魯棒解析先嘗試 JSON解析失敗則拋異常 try: parsed json.loads(content) except json.JSONDecodeError as exc: raise LLMClientError( fmodel returned invalid json. content{content[:200]} ) from exc # 用 Pydantic 校驗(yàn)結(jié)構(gòu) try: validated response_model.model_validate(parsed) except ValidationError as exc: raise LLMClientError(fschema validation failed: {exc}) from exc log_llm_call( prompt_versionprompt_version, modelself.model, latency_ms(time.perf_counter() - start) * 1000, output_hashhash(content), validation_okTrue, ) return validated except httpx.HTTPError as exc: log_llm_call( prompt_versionprompt_version, modelself.model, latency_ms(time.perf_counter() - start) * 1000, errorstr(exc), validation_okFalse, ) raise LLMClientError(fhttp request failed: {exc}) from exc這個(gè)封裝有幾個(gè)值得學(xué)習(xí)的地方response_format強(qiáng)制模型輸出 JSON 對(duì)象減少 Markdown 干擾。用 Pydantic 模型做二次校驗(yàn)保證下游拿到的一定是合法結(jié)構(gòu)。output_hash用于日志追蹤方便后續(xù)對(duì)比相同請(qǐng)求的輸出是否變化。4.4 增加緩存層緩存是為了解決兩個(gè)問題第一是降低成本和延遲第二是讓確定性請(qǐng)求不受模型漂移影響。但緩存鍵必須包含版本信息確保 prompt 或 schema 升級(jí)時(shí)能自動(dòng)繞過舊緩存。# 文件路徑src/llm_gateway/cache.py import hashlib import json import time from typing import Any, Optional import redis.asyncio as redis class SemanticCache: def __init__(self, redis_url: str, default_ttl: int 300): self.client redis.from_url(redis_url, decode_responsesTrue) self.default_ttl default_ttl staticmethod def _build_key( model: str, prompt_version: str, schema_version: str, messages: list[dict[str, str]], ) - str: raw json.dumps( { model: model, prompt_version: prompt_version, schema_version: schema_version, messages: messages, }, ensure_asciiFalse, sort_keysTrue, ) return llm: hashlib.sha256(raw.encode()).hexdigest() async def get(self, key: str) - Optional[str]: return await self.client.get(key) async def set(self, key: str, value: str, ttl: Optional[int] None) - None: await self.client.set(key, value, exttl or self.default_ttl)緩存方案其實(shí)有多種選擇精確緩存請(qǐng)求消息完全一致直接返回歷史結(jié)果。適合客服回復(fù)、意圖識(shí)別等重復(fù)性高的場景。語義緩存通過向量相似度匹配相似請(qǐng)求適合 FAQ 場景。語義緩存復(fù)雜度更高需要控制相似度閾值避免誤命中。臨時(shí)禁用對(duì)實(shí)時(shí)性要求極高的場景可以只做短期 TTL 緩存。上面的示例是精確緩存。業(yè)務(wù)上如果遇到相同用戶重復(fù)問同一個(gè)問題也會(huì)直接命中緩存這通常是合理的。4.5 加入重試與降級(jí)網(wǎng)絡(luò)抖動(dòng)、模型服務(wù)超時(shí)是常態(tài)。但重試和降級(jí)不能亂來否則會(huì)在模型側(cè)造成更大壓力也會(huì)掩蓋漂移問題。# 文件路徑src/llm_gateway/fallback.py import asyncio from typing import Awaitable, Callable, TypeVar from .client import LLMClientError T TypeVar(T) async def with_retry( func: Callable[[], Awaitable[T]], retries: int 2, backoff_seconds: float 0.5, ) - T: last_exc: Exception | None None for attempt in range(retries 1): try: return await func() except LLMClientError as exc: last_exc exc # 不是所有異常都應(yīng)該重試只有網(wǎng)絡(luò)類錯(cuò)誤才重試 if http request failed not in str(exc): raise if attempt retries: await asyncio.sleep(backoff_seconds * (2**attempt)) raise last_exc # type: ignore這段代碼只對(duì)網(wǎng)絡(luò)類錯(cuò)誤保留重試能力。對(duì)于 schema 校驗(yàn)失敗、模型返回非法 JSON 這類問題重試沒有意義反而會(huì)把錯(cuò)誤掩蓋掉所以直接拋出讓上層感知并轉(zhuǎn)人工兜底。降級(jí)策略方面我建議按照“自動(dòng)處理 → 有限重試 → 人工兜底”的順序設(shè)計(jì)。不能讓模型失敗時(shí)靜默返回一個(gè)默認(rèn)結(jié)果因?yàn)槟菢訒?huì)掩蓋真實(shí)問題。寧可讓用戶等待或轉(zhuǎn)人工也不要在后臺(tái)吞掉異常。4.6 組裝業(yè)務(wù)調(diào)用入口把上面幾個(gè)模塊組合起來就是業(yè)務(wù)層看到的穩(wěn)定調(diào)用入口。業(yè)務(wù)代碼不再直接面對(duì)模型 SDK而是面對(duì)一個(gè)帶有緩存和重試能力的 gateway。# 文件路徑src/llm_gateway/gateway.py from typing import Optional from .cache import SemanticCache from .client import LLMClient, LLMClientError from .fallback import with_retry from .schema import IntentResponse from prompts.intent import PROMPT_VERSION, build_intent_messages class LLMGateway: def __init__( self, api_base: str, api_key: str, model: str, redis_url: str, schema_version: str, ): self.client LLMClient(api_baseapi_base, api_keyapi_key, modelmodel) self.cache SemanticCache(redis_url) self.model model self.schema_version schema_version async def classify_intent( self, user_input: str, rules: list[str], use_cache: bool True ) - IntentResponse: messages build_intent_messages(user_input, rules) cache_key self.cache._build_key( modelself.model, prompt_versionPROMPT_VERSION, schema_versionself.schema_version, messagesmessages, ) if use_cache: cached await self.cache.get(cache_key) if cached: import json return IntentResponse.model_validate(json.loads(cached)) async def call_model(): return await self.client.chat_json( messagesmessages, response_modelIntentResponse, prompt_versionPROMPT_VERSION, ) try: resp await with_retry(call_model, retries2) if use_cache: await self.cache.set(cache_key, resp.model_dump_json()) return resp except LLMClientError as exc: # 生產(chǎn)環(huán)境應(yīng)在此處上報(bào)監(jiān)控并觸發(fā)人工兜底 raise注意業(yè)務(wù)代碼捕獲到LLMClientError后應(yīng)該做兩件事上報(bào)監(jiān)控指標(biāo)并觸發(fā)降級(jí)流程。示例里沒有吞掉異常這正是穩(wěn)定邊界的關(guān)鍵。5. 建立回歸評(píng)估體系讓漂移無處可藏接入層穩(wěn)定還不夠你還需要一套能自動(dòng)判斷“模型行為是否回歸”的機(jī)制。這是阻止漂移進(jìn)入生產(chǎn)環(huán)境的核心手段。5.1 金標(biāo)數(shù)據(jù)集Golden Set金標(biāo)數(shù)據(jù)集是一組帶期望輸出的測試樣本。它不需要覆蓋所有場景但必須覆蓋核心業(yè)務(wù)鏈路、易錯(cuò)邊界和已知坑點(diǎn)。# 文件路徑evaluate/golden_set.jsonl {user_input: 我想退貨訂單號(hào)是12345, expected: {can_not_handle: false, result: {intent: aftersale, confidence: 0.9, product_keyword: null, raw_reply_short: 您好請(qǐng)問訂單號(hào)是多少}}} {user_input: 這件衣服有黑色嗎, expected: {can_not_handle: false, result: {intent: presale, confidence: 0.9, product_keyword: 衣服, raw_reply_short: 稍等我?guī)湍樵儙齑鎪}} {user_input: 你們公司幾點(diǎn)下班, expected: {can_not_handle: true, result: null}}這個(gè)數(shù)據(jù)集要放進(jìn) git 倉庫隨著業(yè)務(wù)迭代持續(xù)補(bǔ)充。每次有人修改 prompt 或升級(jí)模型都需要用新數(shù)據(jù)集跑一遍。5.2 自動(dòng)評(píng)估腳本# 文件路徑evaluate/run_evaluation.py import asyncio import json import os from pathlib import Path from src.llm_gateway.gateway import LLMGateway async def load_golden_set(file_path: str) - list[dict]: items [] with Path(file_path).open() as f: for line in f: line line.strip() if line: items.append(json.loads(line)) return items def check_response( actual: dict, expected: dict ) - tuple[bool, dict]: # 簡化版校驗(yàn)can_not_handle 必須一致intent 必須一致置信度不低于 0.85 期望值 if actual.get(can_not_handle) ! expected.get(can_not_handle): return False, {field: can_not_handle, expected: expected, actual: actual} if not expected.get(can_not_handle): if actual[result][intent] ! expected[result][intent]: return False, {field: intent, expected: expected, actual: actual} if actual[result][confidence] 0.85: return False, {field: confidence, expected: 0.85, actual: actual[result][confidence]} return True, {} async def main() - None: golden_set await load_golden_set(evaluate/golden_set.jsonl) api_base os.environ[LLM_API_BASE] api_key os.environ[LLM_API_KEY] model os.environ.get(LLM_MODEL, gpt-4o-mini) gateway LLMGateway( api_baseapi_base, api_keyapi_key, modelmodel, redis_urlredis://localhost:6379, schema_versionintent-schema-v1, ) passed 0 results [] for item in golden_set: user_input item[user_input] expected item[expected] try: resp await gateway.classify_intent( user_input, rules[支持退貨和換貨], use_cacheFalse ) actual resp.model_dump() ok, reason check_response(actual, expected) if ok: passed 1 else: results.append({user_input: user_input, ok: False, reason: reason}) except Exception as exc: results.append({user_input: user_input, ok: False, reason: str(exc)}) total len(golden_set) pass_rate passed / total print(fpass rate: {pass_rate:.2%} ({passed}/{total})) for r in results: print(json.dumps(r, ensure_asciiFalse, indent2)) # 閾值設(shè)置建議根據(jù)業(yè)務(wù)容忍度調(diào)整 threshold 0.9 if pass_rate threshold: raise SystemExit(f評(píng)估未通過通過率 {pass_rate:.2%} {threshold:.2%}) if __name__ __main__: asyncio.run(main())閾值設(shè)置要結(jié)合業(yè)務(wù)容忍度。如果評(píng)估集本身就包含邊界 case90% 是合理底線如果評(píng)估集只覆蓋主流程建議提高到 98% 以上。關(guān)鍵是寧可發(fā)布慢一點(diǎn)也不要讓漂移悄悄進(jìn)生產(chǎn)。5.3 接入 CI 流水線評(píng)估腳本只有跑在自動(dòng)化流程里才有價(jià)值。下面以一個(gè)常見 CI 配置為例。# 文件路徑.github/workflows/evaluate.yml name: LLM Evaluation on: pull_request: paths: - prompts/** - src/llm_gateway/** - evaluate/** push: branches: [main] paths: - prompts/** - src/llm_gateway/** - evaluate/** jobs: evaluate: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: 3.10 - run: pip install -e .[dev] - run: pytest tests/ - run: python evaluate/run_evaluation.py env: LLM_API_BASE: ${{ secrets.LLM_API_BASE }} LLM_API_KEY: ${{ secrets.LLM_API_KEY }} LLM_MODEL: ${{ secrets.LLM_MODEL }}等 CI 跑通之后你就會(huì)發(fā)現(xiàn)一個(gè)非常有用的轉(zhuǎn)變從“誰能保證模型行為沒變”變成“CI 已經(jīng)在自動(dòng)檢查了閾值沒過就看不到合入口”。這才是生產(chǎn)代碼庫應(yīng)有的確定性。6. 生產(chǎn)監(jiān)控與漂移檢測評(píng)估只能覆蓋你寫過的樣本線上真實(shí)用戶的輸入分布要廣得多。所以生產(chǎn)監(jiān)控同樣不可缺少。6.1 結(jié)構(gòu)化日志結(jié)構(gòu)化日志是監(jiān)控的基礎(chǔ)。每一次 LLM 調(diào)用都要記錄prompt 版本、schema 版本、模型 ID、輸入哈希、輸出哈希、延遲、token 用量、是否命中緩存、是否有異常。# 文件路徑src/llm_gateway/monitor.py import hashlib import json import logging import time logger logging.getLogger(llm_gateway) handler logging.StreamHandler() formatter logging.Formatter( %(asctime)s %(levelname)s %(name)s %(message)s ) handler.setFormatter(formatter) logger.addHandler(handler) logger.setLevel(logging.INFO) def _stable_hash(value: str) - str: return hashlib.sha256(value.encode()).hexdigest()[:16] def log_llm_call( prompt_version: str, model: str, latency_ms: float, output_hash: str , validation_ok: bool True, error: str , extra: dict | None None, ) - None: data { event: llm_call, prompt_version: prompt_version, model: model, latency_ms: round(latency_ms, 1), output_hash: output_hash, validation_ok: validation_ok, error: error, timestamp: int(time.time()), **extra, } logger.info(json.dumps(data, ensure_asciiFalse))注意日志里不要記錄完整的用戶輸入和完整模型輸出避免隱私和合規(guī)問題。記錄哈希值已經(jīng)足夠用于追蹤和對(duì)比。6.2 監(jiān)控指標(biāo)建議如果使用 Prometheus 或云監(jiān)控建議至少采集以下指標(biāo)指標(biāo)名稱類型說明llm_request_totalCounter總請(qǐng)求數(shù)按模型/prompt版本拆分llm_failure_totalCounter失敗請(qǐng)求數(shù)按錯(cuò)誤類型拆分llm_latency_secondsHistogram延遲分布llm_schema_validation_failure_totalCounterschema 校驗(yàn)失敗次數(shù)漂移信號(hào)之一llm_cache_hit_ratioGauge緩存命中率llm_output_hash_counterGauge相同發(fā)送哈希下輸出哈希分布變化嚴(yán)重程度schema 校驗(yàn)失敗率上升是一個(gè)非常強(qiáng)的漂移信號(hào)。如果平時(shí)校驗(yàn)失敗率低于 0.1%某天突然漲到 2%第一反應(yīng)不應(yīng)該是修代碼而是要檢查模型輸出格式是不是變了。6.3 灰度與金絲雀發(fā)布當(dāng)你要升級(jí)模型版本、換品牌模型或調(diào)整 prompt 時(shí)不要直接全量。建議通過灰度策略引入新版本比如先讓 5% 流量走新版本觀察 schema 校驗(yàn)失敗率、用戶反饋、延遲指標(biāo)再逐步擴(kuò)大?；叶绕陂g日志里的model字段和prompt_version字段會(huì)派上大用場。你可以對(duì)比新舊版本在同一批真實(shí)輸入上的表現(xiàn)差異。7. 常見問題與排查思路下面整理了一些生產(chǎn)環(huán)境里最常見的漂移相關(guān)問題和排查思路。問題現(xiàn)象常見原因解決思路相同 prompt 輸出內(nèi)容每天不一樣模型遠(yuǎn)端更新temperature 不為 0上下文參雜了變化信息固定 temperature0檢查 prompt 模板版本對(duì)比日志 output_hash解析失敗率突然上升模型輸出格式漂移response_format 未生效schema 校驗(yàn)過嚴(yán)查看最近請(qǐng)求的原始輸出確認(rèn)是否切換模型臨時(shí)放寬校驗(yàn)并人工 review緩存命中率過高但業(yè)務(wù)反饋結(jié)果過時(shí)緩存鍵中版本不完整TTL 太長檢查緩存鍵是否包含 prompt 和 schema 版本動(dòng)態(tài)調(diào)短 TTL評(píng)估通過但線上效果差金標(biāo)集覆蓋不足線上輸入分布偏移擴(kuò)大評(píng)估集加入線上真實(shí)脫敏樣本建立線上質(zhì)量抽檢機(jī)制模型調(diào)用延遲突然翻倍模型服務(wù)繁忙輸入 token 長度上漲重試風(fēng)暴查看延遲分位數(shù)增加熔斷檢查是否有大量重試疊加換一個(gè)模型后指標(biāo)全面下降prompt 風(fēng)格和舊模型不匹配schema 格式要求理解不到位先跑評(píng)估腳本對(duì)比根據(jù)新模型 output 微調(diào) prompt但必須更新版本號(hào)排查時(shí)有一個(gè)很重要的原則不要把眼光局限在代碼 diff 上。先看日志和指標(biāo)確認(rèn)變化發(fā)生的時(shí)間點(diǎn)再反推當(dāng)時(shí)有哪些變量變了模型服務(wù)、prompt 版本、schema 版本、上下文策略、知識(shí)庫更新、線上配置開關(guān)。其中任何一個(gè)變化都可能觸發(fā)漂移。8. 最佳實(shí)踐與工程建議到這里穩(wěn)定化方案已經(jīng)完整了。最后再整理幾條生產(chǎn)環(huán)境里踩過坑后沉淀下來的建議。8.1 把 prompt 當(dāng)作代碼管理prompt 必須進(jìn) git、帶版本號(hào)、走 code review。不要允許業(yè)務(wù)方直接改線上配置里的 prompt 字符串。建議單獨(dú)建立prompts/目錄每個(gè) prompt 文件包含版本常量所有修改通過 PR 合入。8.2 輸出 schema 先行在寫業(yè)務(wù)邏輯之前先定義輸出 schema。業(yè)務(wù)邏輯只消費(fèi)校驗(yàn)后的 Pydantic 對(duì)象不消費(fèi)原始字符串。這樣即使模型輸出漂移你也能在 gateway 層快速感知而不是讓臟數(shù)據(jù)穿透到數(shù)據(jù)庫或用戶界面。8.3 讓失敗可見而不是靜默降級(jí)很多初學(xué)者喜歡在異常里返回一個(gè)默認(rèn)值看起來“穩(wěn)定”實(shí)際上是在掩蓋問題。生產(chǎn)環(huán)境應(yīng)該讓失敗可觀測上報(bào)指標(biāo)、記錄日志、觸發(fā)人工兜底。寧可讓用戶等待也不能讓錯(cuò)誤數(shù)據(jù)進(jìn)入正常流程。8.4 評(píng)估集要持續(xù)增量每次找到線上 bad case就把它加入金標(biāo)數(shù)據(jù)集。評(píng)估集越貼近真實(shí)輸入分布CI 防線越牢固。建議每個(gè)迭代周期至少 review 一次評(píng)估集移除已經(jīng)不再相關(guān)的樣本新增最近發(fā)現(xiàn)的坑點(diǎn)。8.5 監(jiān)控要設(shè)閾值和告警沒有告警的監(jiān)控等于沒有監(jiān)控。建議至少對(duì)以下場景設(shè)置告警schema 校驗(yàn)失敗率連續(xù) 5 分鐘超過 1%。LLM 調(diào)用錯(cuò)誤率超過 5%。緩存命中率意外驟降可能緩存鍵設(shè)計(jì)被破壞。評(píng)估腳本在 CI 中失敗直接阻斷發(fā)布。8.6 安全與合規(guī)邊界LLM 應(yīng)用涉及用戶數(shù)據(jù)時(shí)務(wù)必在 gateway 層做好脫敏和日志控制。核心建議日志不記錄完整用戶輸入輸出只保留哈?；蛎撁羝巍?duì)外部模型的請(qǐng)求增加內(nèi)容過濾避免敏感信息外泄。涉及用戶個(gè)人信息時(shí)確認(rèn)是否允許將數(shù)據(jù)發(fā)送給第三方模型服務(wù)必要時(shí)自建私有化模型網(wǎng)關(guān)。8.7 分階段推進(jìn)的路線圖如果你正在接手一個(gè)已經(jīng)上線的 LLM 項(xiàng)目不要一次性引入上面所有機(jī)制那樣風(fēng)險(xiǎn)太高。建議按以下順序推進(jìn)第一階段增加結(jié)構(gòu)化日志與輸出哈希建立基礎(chǔ)監(jiān)控。第二階段引入 Pydantic schema 校驗(yàn)確保業(yè)務(wù)層只消費(fèi)合法結(jié)構(gòu)。第三階段封裝統(tǒng)一 gateway加入緩存與重試。第四階段建立金標(biāo)評(píng)估集并接入 CI。第五階段增加告警、灰度與 canary 發(fā)布機(jī)制。當(dāng)你走完這五個(gè)階段代碼庫不會(huì)再被 LLM 的隨機(jī)性牽著走。每一次模型升級(jí)、prompt 調(diào)整、SDK 更新都可以像普通后端變更一樣有回歸預(yù)期、有監(jiān)控?cái)?shù)據(jù)、有安全兜底。如果你最近也被線上 LLM 行為不穩(wěn)定困擾建議先按照第六節(jié)的指標(biāo)清單查一遍日志看看輸出哈希在一天內(nèi)是不是開始劇烈變化。確認(rèn)了漂移信號(hào)之后再動(dòng)手搭建本文這套穩(wěn)定邊界。有了版本鎖定、結(jié)構(gòu)化輸出、評(píng)估回歸、監(jiān)控告警這四道防線LLM 在生產(chǎn)代碼庫里也能穩(wěn)定得像普通軟件一樣。