代類型安全：用Schema-First與運(yùn)行時(shí)校驗(yàn)約束AI代碼生成)
如果你最近在用大模型寫代碼大概率經(jīng)歷過這種場面讓 LLM 生成一個(gè) Python 函數(shù)它寫得又快又像模像樣結(jié)果一跑就報(bào)TypeError或者讓它調(diào)一個(gè)第三方 SDK它憑“印象”編出一個(gè)不存在的參數(shù)你查文檔半天才確認(rèn)是幻覺。到了這一步很多人會得出一個(gè)結(jié)論大模型代碼不可靠還是自己寫吧。但這是一個(gè)值得重新審視的判斷。LLM 時(shí)代真正變化的不是“要不要寫代碼”而是“代碼質(zhì)量的第一道防線放在哪里”。過去這道防線是人程序員靠經(jīng)驗(yàn)、規(guī)范、Review 去控制質(zhì)量。現(xiàn)在生成代碼的主力變成了模型每小時(shí)能產(chǎn)出數(shù)千行人不可能逐行把關(guān)。這時(shí)候類型系統(tǒng)反而成了比以往更重要的基礎(chǔ)設(shè)施——它不再只是編譯期幫你抓 bug 的工具而是 AI 與開發(fā)者之間的“通信協(xié)議”。這篇文章想講清楚三件事第一LLM 時(shí)代類型安全為什么不僅沒有過時(shí)反而更重要了第二LLM 對類型系統(tǒng)的理解邊界到底在哪里為什么它寫代碼時(shí)總會“差不多先生”第三如何用 Schema-First、結(jié)構(gòu)化輸出、運(yùn)行時(shí)校驗(yàn)這些工程手段把大模型生成代碼的類型風(fēng)險(xiǎn)壓到可控范圍。文中會給出 Python、TypeScript 和 Agent 配置三類可落地的示例并附上排錯(cuò)清單。1. LLM 時(shí)代類型安全為什么成了新問題如果不寫代碼只看各種大模型的 Demo很容易產(chǎn)生一個(gè)錯(cuò)覺AI 已經(jīng)會寫代碼了那類型系統(tǒng)這種“老古董”是不是該退場了恰恰相反LLM 時(shí)代的類型安全問題比純?nèi)斯ぞ幋a時(shí)代更尖銳原因有三個(gè)。第一個(gè)原因是代碼生產(chǎn)速度與人工審查速度的剪刀差。過去一個(gè)人一天寫幾百行代碼類型錯(cuò)誤靠編譯器加 Code Review 基本能兜住?，F(xiàn)在一個(gè)團(tuán)隊(duì)可能同時(shí)跑十幾個(gè) Agent 任務(wù)每個(gè)任務(wù)生成幾百上千行代碼瞬間產(chǎn)出量遠(yuǎn)超人力審查能力。如果沒有類型系統(tǒng)在生成階段就掐掉一批錯(cuò)誤靠人來復(fù)查本質(zhì)上是在用 20 世紀(jì)的流程管理 21 世紀(jì)的產(chǎn)能遲早失控。第二個(gè)原因是 LLM 對類型系統(tǒng)的“理解”是概率性的。模型在訓(xùn)練時(shí)見過海量代碼因此能學(xué)會“看起來像類型安全代碼”的統(tǒng)計(jì)模式。但它在生成時(shí)并不像編譯器那樣做符號解析和類型推導(dǎo)它是在做 Token 序列的概率預(yù)測。這意味著它寫出的代碼可以極其流暢、極其規(guī)范卻仍然包含類型層面的錯(cuò)誤函數(shù)簽名對不上、可空值沒有判空、把字符串當(dāng)數(shù)字傳、序列化邊界類型不一致等等。這些問題在語法上完全合法卻會在運(yùn)行時(shí)爆炸。第三個(gè)原因是 AI 編程的協(xié)作鏈路變長了。以前是人寫代碼、機(jī)器編譯出錯(cuò)鏈路短?，F(xiàn)在是人設(shè)計(jì)提示詞、模型生成代碼、工具鏈執(zhí)行代碼、模型再根據(jù)錯(cuò)誤反饋修復(fù)代碼這是一個(gè)多輪反饋回路。每一輪模型都在“猜測”數(shù)據(jù)結(jié)構(gòu)和類型契約如果沒有穩(wěn)定的類型層做錨點(diǎn)這個(gè)回路會陷入越修越亂的死循環(huán)模型猜一個(gè)類型報(bào)錯(cuò)再猜一個(gè)再報(bào)錯(cuò)。所以更準(zhǔn)確的判斷是LLM 時(shí)代類型安全從“工程質(zhì)量問題”升級成了“AI 協(xié)作的基礎(chǔ)設(shè)施問題”。它決定了你手里的大模型是生產(chǎn)力工具還是 bug 生成器。2. 核心概念類型安全、靜態(tài)類型、動態(tài)類型與 LLM 的認(rèn)知邊界要討論這個(gè)主題先把幾個(gè)容易混淆的概念理清楚。類型安全Type Safety是指程序在運(yùn)行時(shí)不會因?yàn)轭愋筒黄ヅ涠a(chǎn)生未定義行為。一個(gè)類型安全的語言會盡可能在錯(cuò)誤發(fā)生前攔截類型問題。靜態(tài)類型Static Typing指類型在編譯期檢查比如 Java、TypeScript、Rust。動態(tài)類型Dynamic Typing指類型在運(yùn)行時(shí)檢查比如 Python、JavaScript。注意動態(tài)類型語言不等于沒有類型安全Python 運(yùn)行時(shí)會檢查類型錯(cuò)誤只是檢查時(shí)機(jī)晚而且很多錯(cuò)誤要等代碼執(zhí)行到那一行才暴露。衡量類型系統(tǒng)強(qiáng)弱還有一個(gè)維度叫類型推導(dǎo)能力?，F(xiàn)代靜態(tài)語言如 TypeScript、Kotlin、Rust 都有很強(qiáng)的局部類型推導(dǎo)能減輕程序員的標(biāo)注負(fù)擔(dān)。這個(gè)能力對 LLM 特別重要因?yàn)槟Ｐ秃苌瞄L生成“看起來類型正確”的代碼而類型推導(dǎo)可以讓編譯器替模型確認(rèn)這一點(diǎn)。用一張表來看四種語言在 LLM 協(xié)作場景下的差異語言類型檢查時(shí)機(jī)類型推導(dǎo)LLM 生成代碼的常見風(fēng)險(xiǎn)適合的協(xié)作方式Python運(yùn)行時(shí)弱參數(shù)類型隨意、None 未處理配合 Pydantic 做運(yùn)行時(shí)校驗(yàn)與 Schema 約束JavaScript運(yùn)行時(shí)弱隱式類型轉(zhuǎn)換、API 參數(shù)傳錯(cuò)配合 JSDoc 或遷移 TypeScriptTypeScript編譯期強(qiáng)類型斷言濫用、API 類型編造直接利用編譯器做 AI 代碼的“自動 Reviewer”Java編譯期中樣板代碼多、泛型邊界復(fù)雜用接口即契約生成代碼后靠編譯期把關(guān)那 LLM 到底“懂不懂”類型嚴(yán)格說它不懂。它沒有類型環(huán)境不做靜態(tài)分析更像是一個(gè)“見過無數(shù)代碼的模仿者”。它的優(yōu)勢在模式匹配見到ListUser這種寫法它知道大概率要遍歷知道user.name大概是個(gè)字符串。它的劣勢在于一旦涉及跨模塊的類型聯(lián)動、泛型約束、復(fù)雜繼承關(guān)系它只能靠猜。這就像一個(gè)看過大量法庭劇的人去寫法律文書語氣很專業(yè)程序上卻可能漏洞百出。理解這一點(diǎn)你就能明白接下來所有工程手段的核心邏輯不要讓 LLM 去“理解”類型而是把類型系統(tǒng)變成它必須遵守的外部約束。3. LLM 生成代碼中的典型類型錯(cuò)誤模式先看幾類在 LLM 生成代碼里反復(fù)出現(xiàn)的類型錯(cuò)誤。這些模式我在各種團(tuán)隊(duì)和開源項(xiàng)目里都見過基本可以算作 AI 編程的“通病”。提前識別它們能省掉大量排錯(cuò)時(shí)間。3.1 隱式 any 與類型逃逸在 TypeScript 里模型特別喜歡在函數(shù)參數(shù)上省略類型注解尤其是在沒有開啟嚴(yán)格模式的項(xiàng)目里// 常見錯(cuò)誤示例參數(shù)沒有類型返回類型也沒有 export function processItems(items) { return items.map((item) item.price * item.count); }這個(gè)函數(shù)能編譯過去但items是anyitem.price也是any。一旦調(diào)用方傳入的數(shù)組元素缺少price字段或price是字符串問題會一路傳播到 UI 層才暴露。LLM 之所以喜歡這么寫是因?yàn)橛?xùn)練數(shù)據(jù)里有大量未標(biāo)注類型的 JavaScript 代碼模型學(xué)到的“平均風(fēng)格”就是少寫類型。正確做法是開啟strict模式讓編譯器強(qiáng)制模型補(bǔ)充類型interface CartItem { price: number; count: number; } export function processItems(items: CartItem[]): number { return items.reduce((sum, item) sum item.price * item.count, 0); }3.2 可空值未處理在 Java 和 Kotlin 里L(fēng)LM 常常生成“可能返回 null 卻直接使用返回值”的代碼。Python 里則是函數(shù)可能返回None但文檔字符串和類型注解完全沒提。這類錯(cuò)誤在動態(tài)類型語言里尤其隱蔽因?yàn)檫\(yùn)行不到那一條分支就不會報(bào)錯(cuò)。3.3 API 簽名幻覺這是最讓人頭疼的一類。模型訓(xùn)練數(shù)據(jù)里有各種 SDK 的舊版本用法于是它會把舊版 API 參數(shù)寫進(jìn)新版本代碼。比如某個(gè) SDK 早期版本用model參數(shù)新版本改成了model_nameLLM 很可能按訓(xùn)練頻率最高的寫法生成代碼——這在類型系統(tǒng)里表現(xiàn)為“參數(shù)不存在”或“類型不匹配”。靜態(tài)類型語言還能報(bào)錯(cuò)動態(tài)類型語言往往要等運(yùn)行時(shí)才能暴露。3.4 序列化邊界類型不一致LLM 生成代碼往往忽略“邊界”概念。后端定義id是數(shù)字JSON 序列化之后前端拿到的可能是字符串?dāng)?shù)據(jù)庫返回Decimal模型直接把它當(dāng)float參與運(yùn)算。這些錯(cuò)誤不是單一模塊內(nèi)的類型錯(cuò)誤而是跨系統(tǒng)、跨語言邊界上的類型斷裂。在 AI 生成代碼的場景里由于模型一次只能看到有限上下文它很難意識到邊界的另一側(cè)是什么類型于是這種錯(cuò)誤特別高頻。識別了這些模式你就知道下一節(jié)要講的方法論為什么是必需的不能只依賴 LLM 的自覺必須用類型系統(tǒng)和 Schema 把它框住。4. Schema-First把類型系統(tǒng)變成 AI 的契約面對 LLM 生成代碼的不確定性當(dāng)前工程界公認(rèn)最有效的策略不是“提示詞寫得再詳細(xì)一點(diǎn)”而是Schema-First契約先行。它的核心思想是在讓模型生成代碼之前先把數(shù)據(jù)結(jié)構(gòu)、接口契約、類型定義用顯式的方式寫清楚并讓這些定義成為整個(gè)流程中不可繞過的約束。這里要引入另一個(gè)熱詞結(jié)構(gòu)化輸出Structured Output。幾乎所有主流 LLM API 現(xiàn)在都支持讓模型按 JSON Schema 返回結(jié)果。這個(gè)能力表面上只是為了“解析方便”實(shí)際上它做了一件極其重要的事把模型輸出從自由文本變成受約束的類型化數(shù)據(jù)。當(dāng)你在 API 調(diào)用里綁定一個(gè) JSON Schema 時(shí)模型要么輸出符合 Schema 的 JSON要么告訴你它做不到這本質(zhì)上就是一次“運(yùn)行時(shí)類型檢查”。同樣的邏輯也適用于代碼生成。與其讓 LLM 自由發(fā)揮寫一個(gè)內(nèi)部實(shí)現(xiàn)不如給它一個(gè)明確的類型簽名讓它只填充函數(shù)體// 業(yè)務(wù)接口已定義好LLM 只需要實(shí)現(xiàn)這個(gè)函數(shù) interface PriceCalculator { calculate(basePrice: number, discountRate: number): number; }當(dāng)類型簽名成為 AI 任務(wù)輸入的一部分模型就會被迫圍繞這個(gè)契約生成代碼而不是自己發(fā)明一個(gè)“更好”的接口。Schema-First 在工程上還有一個(gè)附帶價(jià)值可測試、可校驗(yàn)、可回滾。因?yàn)槠跫s是顯式的你可以對 AI 產(chǎn)出物做自動化驗(yàn)證。如果驗(yàn)證不通過要么讓模型重試要么標(biāo)記失敗走人工。這比“看一眼代碼感覺沒問題”靠譜得多。5. 實(shí)操示例一Python Pydantic 約束 LLM 輸出理論說完了下面用一個(gè)最小示例演示如何用 Pydantic 給 LLM 輸出加一道類型安全閘門。這個(gè)場景非常常見讓模型從一段文本里抽取結(jié)構(gòu)化信息然后寫進(jìn)數(shù)據(jù)庫或交給下游服務(wù)處理。5.1 環(huán)境準(zhǔn)備本文示例基于 Python 3.10 以上版本核心依賴如下。版本號請以你實(shí)際項(xiàng)目的鎖定版本為準(zhǔn)這里重點(diǎn)演示通用思路。pip install pydantic openai如果你用的不是 OpenAI 兼容接口換成 Anthropic、本地部署模型或其他 SDK 也一樣核心方法是通用的。5.2 定義輸出模型用一個(gè)數(shù)據(jù)類來描述我們期望的模型輸出結(jié)構(gòu)# 文件路徑schemas/order.py from datetime import datetime from typing import Literal from pydantic import BaseModel, Field, ValidationError class OrderInfo(BaseModel): order_id: str Field(description訂單號) amount: float Field(gt0, description訂單金額必須大于 0) currency: str Field(patternr^[A-Z]{3}$, descriptionISO 貨幣代碼例如 CNY、USD) status: Literal[pending, paid, cancelled] Field(description訂單狀態(tài)) paid_at: datetime | None Field(defaultNone, description支付時(shí)間未支付則為 null)這個(gè)模型做了幾件事amount: float并要求大于 0防止模型輸出負(fù)數(shù)或字符串金額。currency用正則約束必須是大寫三字母避免模型寫出人民幣這種無法解析的值。status用Literal限定取值范圍。paid_at可空防止模型隨意編造支付時(shí)間。5.3 調(diào)用 LLM 并做校驗(yàn)接下來調(diào)用模型并要求它返回 JSON然后用模型做解析校驗(yàn)# 文件路徑llm_order_parser.py import json from openai import OpenAI from schemas.order import OrderInfo, ValidationError client OpenAI(api_keysk-你的密鑰) # 生產(chǎn)環(huán)境請使用環(huán)境變量注入 prompt 從下面的訂單對話中提取訂單信息嚴(yán)格按照 JSON 格式返回 { order_id: 訂單號, amount: 金額數(shù)字, currency: 三位大寫貨幣代碼, status: pending/paid/cancelled 之一, paid_at: ISO 8601 時(shí)間或 null } 對話內(nèi)容用戶說已經(jīng)付款 299.9 元人民幣訂單號是 A12345。 resp client.chat.completions.create( modelgpt-4o-mini, # 以你實(shí)際可用的模型為準(zhǔn) messages[{role: user, content: prompt}], response_format{type: json_object}, # 部分接口支持按需開啟 ) raw json.loads(resp.choices[0].message.content) try: order OrderInfo.model_validate(raw) print(校驗(yàn)通過, order.model_dump()) except ValidationError as e: print(模型輸出不合法拒絕入庫) print(e.json())5.4 關(guān)鍵邏輯解釋model_validate(raw)這一步是全部流程的核心。它把模型輸出的自由 JSON 強(qiáng)制轉(zhuǎn)換成OrderInfo類型。如果模型少傳字段、傳錯(cuò)類型、金額為負(fù)數(shù)、狀態(tài)值不在枚舉里都會在這里拋出ValidationError。此時(shí)正確的處理不是“寬容地修一下再入庫”而是視為一次失敗生成記錄日志讓模型重試或進(jìn)入人工審核。這就是類型安全在大模型時(shí)代的具體形態(tài)你沒法保證模型不犯錯(cuò)但你可以保證錯(cuò)誤的產(chǎn)物到不了下游系統(tǒng)。運(yùn)行之后如果模型輸出正確你會看到類似校驗(yàn)通過 {order_id: A12345, amount: 299.9, ...}的結(jié)果。如果故意把提示詞改成“訂單金額是免費(fèi)”模型可能輸出amount0從而觸發(fā)gt0的校驗(yàn)失敗這正是我們想要的保護(hù)。6. 實(shí)操示例二TypeScript Zod 校驗(yàn) LLM 輸出Python 生態(tài)用 PydanticTypeScript 生態(tài)對應(yīng)的答案是 Zod。它們的思路一致先定義 Schema再校驗(yàn)外部數(shù)據(jù)。在 Node.js 服務(wù)里接入 LLM 時(shí)這種模式幾乎是標(biāo)配。6.1 安裝依賴npm install zod openai6.2 定義 Schema// 文件路徑src/schemas/analysis.ts import { z } from zod; export const AnalysisResult z.object({ topic: z.string().min(1).describe(分析主題), score: z.number().min(0).max(100).describe(主題匹配度0-100), tags: z.array(z.string()).max(10).describe(標(biāo)簽列表最多 10 個(gè)), summary: z.string().max(500).describe(不超過 500 字的總結(jié)), }); export type AnalysisResult z.infertypeof AnalysisResult;注意這里的describe方法。Zod 可以把 Schema 自動轉(zhuǎn)換成 JSON Schema而 JSON Schema 可以直接傳給支持結(jié)構(gòu)化輸出的 LLM 接口讓模型在生成階段就受到約束。這形成了一個(gè)很好的閉環(huán)同一個(gè) Schema 既用來約束模型輸出又用來校驗(yàn)實(shí)際返回。6.3 請求與校驗(yàn)// 文件路徑src/llm.ts import OpenAI from openai; import { AnalysisResult, AnalysisResult as AnalysisSchema } from ./schemas/analysis; const client new OpenAI({ apiKey: process.env.OPENAI_API_KEY }); export async function analyzeText(text: string): PromiseAnalysisResult { const resp await client.chat.completions.create({ model: gpt-4o-mini, messages: [ { role: user, content: 請分析下面文本的主題返回 JSON。文本${text}, }, ], response_format: { type: json_schema, json_schema: { name: analysis_result, schema: AnalysisSchema, // Zod 轉(zhuǎn)成的 JSON Schema strict: true, }, }, }); const content resp.choices[0]?.message.content; if (!content) { throw new Error(模型返回為空); } // 即使模型端做了約束這里仍然再做一次運(yùn)行時(shí)校驗(yàn) const parsed AnalysisResult.safeParse(JSON.parse(content)); if (!parsed.success) { console.error(LLM 輸出校驗(yàn)失敗, parsed.error.flatten()); throw new Error(模型輸出不滿足契約); } return parsed.data; }這段代碼體現(xiàn)了一個(gè)重要的工程原則不要在單一環(huán)節(jié)信任任何一方。哪怕模型端已經(jīng)配置了 JSON Schema 約束返回?cái)?shù)據(jù)也要safeParse一次。原因很簡單模型可能因?yàn)樯舷挛慕財(cái)喾祷貧埲?JSON可能返回空內(nèi)容可能在流式輸出時(shí)被中斷。運(yùn)行時(shí)校驗(yàn)是最后一道閘門閘門不能省。7. 知識庫與提示詞的類型化LLM Wiki 的啟示除了讓模型直接生成代碼另一個(gè)越來越常見的場景是把團(tuán)隊(duì)的領(lǐng)域知識、代碼規(guī)范、歷史決策整理成資料喂給 LLM 作為上下文。這個(gè)方向在社區(qū)里有個(gè)很有名的實(shí)踐就是所謂“LLM Wiki”的思路——用結(jié)構(gòu)化的 Markdown 知識庫來管理喂給模型的內(nèi)容。傳說中 Andrej Karpathy 分享的 LLM Wiki 工作流核心并不是“建一個(gè)維基”而是把知識寫成模型容易消費(fèi)的格式。這項(xiàng)工作看起來跟類型安全無關(guān)實(shí)際上關(guān)系極大。因?yàn)樘崾驹~里的概念定義不清晰本質(zhì)上是“語義層的類型不安全”。你在提示詞里寫了一個(gè)術(shù)語“訂單”但沒說明訂單有哪些字段、狀態(tài)有幾種、金額用什么單位模型就只能靠訓(xùn)練語料里的統(tǒng)計(jì)分布猜測。猜來猜去就產(chǎn)生了前面說的 API 幻覺、字段發(fā)明、邊界類型錯(cuò)誤。所以更準(zhǔn)確地說LLM Wiki 是給模型用的“類型定義文件”。比自然語言描述更可靠的形式是結(jié)構(gòu)化 Schema。下面是一個(gè) Agent 配置示例展示了如何把知識庫內(nèi)容也“類型化”# 文件路徑agents/order-assistant.yaml name: order_assistant description: 負(fù)責(zé)處理訂單查詢和售后申請的客服 Agent context_files: - docs/order-schema.md - docs/policy-refund.md knowledge_schema: order: fields: order_id: string amount: number currency: ISO_4217 status: enum[pending, paid, cancelled, refunded] created_at: ISO_8601 invariants: - amount 0 - refund 僅允許在 status paid 時(shí)發(fā)起 tools: - name: query_order params_schema: { order_id: string } returns_schema: { order: knowledge_schema.order }這份配置的價(jià)值在于它把模型完成任務(wù)所需的概念邊界用顯式的 Schema 描述出來了。模型不再需要“猜”訂單狀態(tài)有哪些取值配置里寫得清清楚楚Agent 框架也可以據(jù)此做參數(shù)校驗(yàn)調(diào)query_order之前先校驗(yàn)order_id格式。這跟 Pydantic/Zod 校驗(yàn)外部輸入是同一個(gè)道理只不過校驗(yàn)對象從模型輸出變成了模型使用的領(lǐng)域概念。從實(shí)踐效果看這種“顯式化”的做法有幾個(gè)直接收益。第一提示詞可以更短因?yàn)轭I(lǐng)域定義不在提示詞里反復(fù)粘貼而在配置文件里引用節(jié)省 Token 也減少前后矛盾。第二新人接手 AGent 配置時(shí)能快速理解系統(tǒng)邊界。第三配置本身可以納入代碼審查和版本管理任何類型定義的變更都有跡可循。如果你手上正好有一個(gè)經(jīng)常“亂說話”的 Agent不妨先檢查一下它的知識庫里到底有沒有清晰的概念定義而不是急著換更強(qiáng)的模型。8. 常見問題與排查思路到了實(shí)操階段你大概率會遇到下面這些狀況。我把高頻問題整理成一張排查表方便你直接對照處理。問題現(xiàn)象可能原因排查方向解決方案LLM 返回 JSON 解析失敗報(bào)Invalid JSON模型輸出被截?cái)嗷蛄魇巾憫?yīng)未完整拼接檢查原始 content 是否以}結(jié)尾開啟流式時(shí)拼接完整使用response_formatJSON 模式失敗重試Pydantic 報(bào)field required模型漏掉了必填字段查看 ValidationError 里缺失的字段名提示詞中給出樣例 JSON開啟結(jié)構(gòu)化輸出必要時(shí)做一輪修正重試金額字段被模型輸出為字符串Schema 聲明了 number 但模型未遵守檢查模型端是否支持 strict 模式在提示詞里寫明“amount 必須是 JSON number不要加引號”用 strict schema模型生成函數(shù)參數(shù)類型和調(diào)用處不匹配上下文窗口沒看到調(diào)用方代碼檢查傳給模型的上下文是否包含目標(biāo)類型定義讓模型先讀接口定義再生成實(shí)現(xiàn)用 TypeScript 強(qiáng)制編譯器兜底同一個(gè)需求多次生成接口風(fēng)格不一致LLM 每次都在“重新發(fā)明”數(shù)據(jù)結(jié)構(gòu)檢查是否提供了穩(wěn)定的類型簽名和示例固定 Schema 文件和示例代碼把已有實(shí)現(xiàn)作為 few-shot 示例Agent 反復(fù)調(diào)用工具失敗報(bào)參數(shù)錯(cuò)誤工具返回 Schema 與實(shí)際實(shí)現(xiàn)不一致檢查工具函數(shù)的運(yùn)行時(shí)校驗(yàn)日志用 Zod/Pydantic 校驗(yàn)工具參數(shù)工具側(cè)增加契約測試結(jié)構(gòu)化輸出請求報(bào)provider rejected the request schemaSchema 格式不被模型接口接受查看接口文檔確認(rèn) JSON Schema 版本和限制簡化 Schema避免過于復(fù)雜的嵌套和anyOf用 SDK 的 Schema 工具類生成模型輸出的字段值合法但語義錯(cuò)誤Schema 只能約束類型不能保證語義人工審視核心業(yè)務(wù)字段增加規(guī)則引擎或正則校驗(yàn)關(guān)鍵字段二次模型復(fù)核排查時(shí)有一條通用原則先確認(rèn)數(shù)據(jù)在哪個(gè)環(huán)節(jié)“變形”了。LLM 輸出鏈路通常經(jīng)過模型生成、JSON 解析、Schema 校驗(yàn)、業(yè)務(wù)使用四段。用日志把每段的數(shù)據(jù)快照打出來基本一眼就能定位是模型猜錯(cuò)了類型、還是解析代碼寫錯(cuò)了、還是校驗(yàn)規(guī)則定得太苛刻。不要在沒看原始輸出的情況下直接懷疑模型很多時(shí)候問題出在提示詞的表述歧義上。9. 最佳實(shí)踐與團(tuán)隊(duì)落地建議9.1 契約先行代碼生成排第二給 LLM 派代碼任務(wù)時(shí)先定義接口、數(shù)據(jù)結(jié)構(gòu)、異常邊界再讓模型實(shí)現(xiàn)內(nèi)部邏輯。這個(gè)順序不能反。如果讓模型先寫實(shí)現(xiàn)它大概率會自己發(fā)明一個(gè)“簡潔好用”但和其他模塊對不上的接口。契約先行之后代碼評審的重點(diǎn)也變了——Review 不再需要逐行看業(yè)務(wù)邏輯只需要重點(diǎn)檢查契約之外的部分。9.2 雙保險(xiǎn)生成時(shí)約束 運(yùn)行時(shí)校驗(yàn)這是整個(gè)流程里最重要的一條建議。生成時(shí)用 JSON Schema / 結(jié)構(gòu)化輸出約束運(yùn)行時(shí)用 Pydantic / Zod 再校驗(yàn)兩層不能相互替代。生成期約束減少無效輸出、省 Token運(yùn)行時(shí)校驗(yàn)保證“無論如何壞數(shù)據(jù)進(jìn)不了下游”。哪怕你的模型接口不支持結(jié)構(gòu)化輸出也一定要保留運(yùn)行時(shí)校驗(yàn)層。9.3 失敗重試要有限次LLM 輸出校驗(yàn)失敗后把錯(cuò)誤信息拼接進(jìn)提示詞讓模型重試一次是有用的做法。但要設(shè)置上限一般 2 到 3 次超過上限直接轉(zhuǎn)人工或標(biāo)記失敗。否則模型可能陷入“改一個(gè)錯(cuò)又引入另一個(gè)錯(cuò)”的循環(huán)既費(fèi) Token 又拖慢鏈路。9.4 為 AI 代碼建立專屬的 Review 流程大模型生成的代碼建議先跑自動化檢查再進(jìn)人工評審。自動化檢查包括編譯/類型檢查、Lint、單測、契約測試、Schema 校驗(yàn)。全部通過后才輪得到人。人工評審時(shí)重點(diǎn)關(guān)注模型最容易犯的三類問題安全邊界、異常處理、外部 API 調(diào)用的真實(shí)性。不要浪費(fèi)時(shí)間在格式和命名上這些交給工具。9.5 把 Schema 納入版本管理無論是 LLM 輸出的數(shù)據(jù)結(jié)構(gòu)、工具函數(shù)的參數(shù) Schema還是 Agent 的知識庫配置都應(yīng)該納入 Git 管理參與 Code Review。你會發(fā)現(xiàn)大多數(shù)“模型突然不聽話”的問題根源都是某個(gè) Schema 被悄悄修改或者知識庫文檔和實(shí)際代碼產(chǎn)生了漂移。9.6 用日志度量類型校驗(yàn)的失敗率建議在運(yùn)行時(shí)校驗(yàn)失敗時(shí)記錄結(jié)構(gòu)化日志字段包括模型、任務(wù)類型、錯(cuò)誤類型、缺失字段、重試次數(shù)。積累一段時(shí)間后你能看出模型在哪些任務(wù)上類型錯(cuò)誤率最高從而有的放矢地優(yōu)化提示詞或 Schema。沒有度量的 AI 工程基本等于盲飛。10. 總結(jié)與后續(xù)學(xué)習(xí)方向回到開頭的問題LLM 時(shí)代類型安全到底重不重要答案不是“重要”而是“比以往更重要且形態(tài)變了”。它不再只是編譯器替你檢查代碼錯(cuò)誤的機(jī)制而成了人和 AI 協(xié)作時(shí)的契約語言。類型系統(tǒng)負(fù)責(zé)把模型“大概差不多”的輸出翻譯成系統(tǒng)能夠安全消費(fèi)的確定結(jié)果。本文的核心結(jié)論可以濃縮成四句話LLM 對類型的理解是概率性的不能依賴它的“自覺”。Schema-First 是約束 AI 輸出的第一原則先定義契約再讓模型干活。生成時(shí)約束和運(yùn)行時(shí)校驗(yàn)必須雙管齊下任何單層信任都有風(fēng)險(xiǎn)。知識庫、提示詞、Agent 配置同樣需要“類型化”模糊的定義必然導(dǎo)致模糊的輸出。如果你剛開始在項(xiàng)目里引入這套思路我建議按這個(gè)順序?qū)嵺`第一步給現(xiàn)有的 LLM 輸出加上一層運(yùn)行時(shí)校驗(yàn)用 Pydantic 或 Zod 先把壞數(shù)據(jù)擋在門外第二步把常用的數(shù)據(jù)結(jié)構(gòu)和接口定義抽成 Schema 文件納入版本管理第三步在提示詞和知識庫中應(yīng)用同樣的顯式化原則讓模型從源頭少犯錯(cuò)。后續(xù)值得深入的方向有幾個(gè)一是學(xué)習(xí)函數(shù)調(diào)用Function Calling的 Schema 設(shè)計(jì)規(guī)范這是 Agent 工具與類型系統(tǒng)交匯最密集的領(lǐng)域二是關(guān)注主流 LLM 框架對結(jié)構(gòu)化輸出支持的演進(jìn)接口在快速變化三是研究一些大型代碼生成任務(wù)中的“類型引導(dǎo)生成”技術(shù)那已經(jīng)不是工程技巧而是研究課題了。對于大多數(shù)開發(fā)團(tuán)隊(duì)來說先把文章里的運(yùn)行時(shí)校驗(yàn)和契約先行落地就已經(jīng)能顯著降低 AI 編程的返工率。建議收藏備用等下次模型又給你寫出一個(gè)隱式any的時(shí)候再回來對照排查表看看。 大模型時(shí)代類型安全：用Schema-First與運(yùn)行時(shí)校驗(yàn)約束AI代碼生成
如果你最近在用大模型寫代碼大概率經(jīng)歷過這種場面讓 LLM 生成一個(gè) Python 函數(shù)它寫得又快又像模像樣結(jié)果一跑就報(bào)TypeError或者讓它調(diào)一個(gè)第三方 SDK它憑“印象”編出一個(gè)不存在的參數(shù)你查文檔半天才確認(rèn)是幻覺。到了這一步很多人會得出一個(gè)結(jié)論大模型代碼不可靠還是自己寫吧。但這是一個(gè)值得重新審視的判斷。LLM 時(shí)代真正變化的不是“要不要寫代碼”而是“代碼質(zhì)量的第一道防線放在哪里”。過去這道防線是人程序員靠經(jīng)驗(yàn)、規(guī)范、Review 去控制質(zhì)量。現(xiàn)在生成代碼的主力變成了模型每小時(shí)能產(chǎn)出數(shù)千行人不可能逐行把關(guān)。這時(shí)候類型系統(tǒng)反而成了比以往更重要的基礎(chǔ)設(shè)施——它不再只是編譯期幫你抓 bug 的工具而是 AI 與開發(fā)者之間的“通信協(xié)議”。這篇文章想講清楚三件事第一LLM 時(shí)代類型安全為什么不僅沒有過時(shí)反而更重要了第二LLM 對類型系統(tǒng)的理解邊界到底在哪里為什么它寫代碼時(shí)總會“差不多先生”第三如何用 Schema-First、結(jié)構(gòu)化輸出、運(yùn)行時(shí)校驗(yàn)這些工程手段把大模型生成代碼的類型風(fēng)險(xiǎn)壓到可控范圍。文中會給出 Python、TypeScript 和 Agent 配置三類可落地的示例并附上排錯(cuò)清單。1. LLM 時(shí)代類型安全為什么成了新問題如果不寫代碼只看各種大模型的 Demo很容易產(chǎn)生一個(gè)錯(cuò)覺AI 已經(jīng)會寫代碼了那類型系統(tǒng)這種“老古董”是不是該退場了恰恰相反LLM 時(shí)代的類型安全問題比純?nèi)斯ぞ幋a時(shí)代更尖銳原因有三個(gè)。第一個(gè)原因是代碼生產(chǎn)速度與人工審查速度的剪刀差。過去一個(gè)人一天寫幾百行代碼類型錯(cuò)誤靠編譯器加 Code Review 基本能兜住?，F(xiàn)在一個(gè)團(tuán)隊(duì)可能同時(shí)跑十幾個(gè) Agent 任務(wù)每個(gè)任務(wù)生成幾百上千行代碼瞬間產(chǎn)出量遠(yuǎn)超人力審查能力。如果沒有類型系統(tǒng)在生成階段就掐掉一批錯(cuò)誤靠人來復(fù)查本質(zhì)上是在用 20 世紀(jì)的流程管理 21 世紀(jì)的產(chǎn)能遲早失控。第二個(gè)原因是 LLM 對類型系統(tǒng)的“理解”是概率性的。模型在訓(xùn)練時(shí)見過海量代碼因此能學(xué)會“看起來像類型安全代碼”的統(tǒng)計(jì)模式。但它在生成時(shí)并不像編譯器那樣做符號解析和類型推導(dǎo)它是在做 Token 序列的概率預(yù)測。這意味著它寫出的代碼可以極其流暢、極其規(guī)范卻仍然包含類型層面的錯(cuò)誤函數(shù)簽名對不上、可空值沒有判空、把字符串當(dāng)數(shù)字傳、序列化邊界類型不一致等等。這些問題在語法上完全合法卻會在運(yùn)行時(shí)爆炸。第三個(gè)原因是 AI 編程的協(xié)作鏈路變長了。以前是人寫代碼、機(jī)器編譯出錯(cuò)鏈路短?，F(xiàn)在是人設(shè)計(jì)提示詞、模型生成代碼、工具鏈執(zhí)行代碼、模型再根據(jù)錯(cuò)誤反饋修復(fù)代碼這是一個(gè)多輪反饋回路。每一輪模型都在“猜測”數(shù)據(jù)結(jié)構(gòu)和類型契約如果沒有穩(wěn)定的類型層做錨點(diǎn)這個(gè)回路會陷入越修越亂的死循環(huán)模型猜一個(gè)類型報(bào)錯(cuò)再猜一個(gè)再報(bào)錯(cuò)。所以更準(zhǔn)確的判斷是LLM 時(shí)代類型安全從“工程質(zhì)量問題”升級成了“AI 協(xié)作的基礎(chǔ)設(shè)施問題”。它決定了你手里的大模型是生產(chǎn)力工具還是 bug 生成器。2. 核心概念類型安全、靜態(tài)類型、動態(tài)類型與 LLM 的認(rèn)知邊界要討論這個(gè)主題先把幾個(gè)容易混淆的概念理清楚。類型安全Type Safety是指程序在運(yùn)行時(shí)不會因?yàn)轭愋筒黄ヅ涠a(chǎn)生未定義行為。一個(gè)類型安全的語言會盡可能在錯(cuò)誤發(fā)生前攔截類型問題。靜態(tài)類型Static Typing指類型在編譯期檢查比如 Java、TypeScript、Rust。動態(tài)類型Dynamic Typing指類型在運(yùn)行時(shí)檢查比如 Python、JavaScript。注意動態(tài)類型語言不等于沒有類型安全Python 運(yùn)行時(shí)會檢查類型錯(cuò)誤只是檢查時(shí)機(jī)晚而且很多錯(cuò)誤要等代碼執(zhí)行到那一行才暴露。衡量類型系統(tǒng)強(qiáng)弱還有一個(gè)維度叫類型推導(dǎo)能力?，F(xiàn)代靜態(tài)語言如 TypeScript、Kotlin、Rust 都有很強(qiáng)的局部類型推導(dǎo)能減輕程序員的標(biāo)注負(fù)擔(dān)。這個(gè)能力對 LLM 特別重要因?yàn)槟Ｐ秃苌瞄L生成“看起來類型正確”的代碼而類型推導(dǎo)可以讓編譯器替模型確認(rèn)這一點(diǎn)。用一張表來看四種語言在 LLM 協(xié)作場景下的差異語言類型檢查時(shí)機(jī)類型推導(dǎo)LLM 生成代碼的常見風(fēng)險(xiǎn)適合的協(xié)作方式Python運(yùn)行時(shí)弱參數(shù)類型隨意、None 未處理配合 Pydantic 做運(yùn)行時(shí)校驗(yàn)與 Schema 約束JavaScript運(yùn)行時(shí)弱隱式類型轉(zhuǎn)換、API 參數(shù)傳錯(cuò)配合 JSDoc 或遷移 TypeScriptTypeScript編譯期強(qiáng)類型斷言濫用、API 類型編造直接利用編譯器做 AI 代碼的“自動 Reviewer”Java編譯期中樣板代碼多、泛型邊界復(fù)雜用接口即契約生成代碼后靠編譯期把關(guān)那 LLM 到底“懂不懂”類型嚴(yán)格說它不懂。它沒有類型環(huán)境不做靜態(tài)分析更像是一個(gè)“見過無數(shù)代碼的模仿者”。它的優(yōu)勢在模式匹配見到ListUser這種寫法它知道大概率要遍歷知道user.name大概是個(gè)字符串。它的劣勢在于一旦涉及跨模塊的類型聯(lián)動、泛型約束、復(fù)雜繼承關(guān)系它只能靠猜。這就像一個(gè)看過大量法庭劇的人去寫法律文書語氣很專業(yè)程序上卻可能漏洞百出。理解這一點(diǎn)你就能明白接下來所有工程手段的核心邏輯不要讓 LLM 去“理解”類型而是把類型系統(tǒng)變成它必須遵守的外部約束。3. LLM 生成代碼中的典型類型錯(cuò)誤模式先看幾類在 LLM 生成代碼里反復(fù)出現(xiàn)的類型錯(cuò)誤。這些模式我在各種團(tuán)隊(duì)和開源項(xiàng)目里都見過基本可以算作 AI 編程的“通病”。提前識別它們能省掉大量排錯(cuò)時(shí)間。3.1 隱式 any 與類型逃逸在 TypeScript 里模型特別喜歡在函數(shù)參數(shù)上省略類型注解尤其是在沒有開啟嚴(yán)格模式的項(xiàng)目里// 常見錯(cuò)誤示例參數(shù)沒有類型返回類型也沒有 export function processItems(items) { return items.map((item) item.price * item.count); }這個(gè)函數(shù)能編譯過去但items是anyitem.price也是any。一旦調(diào)用方傳入的數(shù)組元素缺少price字段或price是字符串問題會一路傳播到 UI 層才暴露。LLM 之所以喜歡這么寫是因?yàn)橛?xùn)練數(shù)據(jù)里有大量未標(biāo)注類型的 JavaScript 代碼模型學(xué)到的“平均風(fēng)格”就是少寫類型。正確做法是開啟strict模式讓編譯器強(qiáng)制模型補(bǔ)充類型interface CartItem { price: number; count: number; } export function processItems(items: CartItem[]): number { return items.reduce((sum, item) sum item.price * item.count, 0); }3.2 可空值未處理在 Java 和 Kotlin 里L(fēng)LM 常常生成“可能返回 null 卻直接使用返回值”的代碼。Python 里則是函數(shù)可能返回None但文檔字符串和類型注解完全沒提。這類錯(cuò)誤在動態(tài)類型語言里尤其隱蔽因?yàn)檫\(yùn)行不到那一條分支就不會報(bào)錯(cuò)。3.3 API 簽名幻覺這是最讓人頭疼的一類。模型訓(xùn)練數(shù)據(jù)里有各種 SDK 的舊版本用法于是它會把舊版 API 參數(shù)寫進(jìn)新版本代碼。比如某個(gè) SDK 早期版本用model參數(shù)新版本改成了model_nameLLM 很可能按訓(xùn)練頻率最高的寫法生成代碼——這在類型系統(tǒng)里表現(xiàn)為“參數(shù)不存在”或“類型不匹配”。靜態(tài)類型語言還能報(bào)錯(cuò)動態(tài)類型語言往往要等運(yùn)行時(shí)才能暴露。3.4 序列化邊界類型不一致LLM 生成代碼往往忽略“邊界”概念。后端定義id是數(shù)字JSON 序列化之后前端拿到的可能是字符串?dāng)?shù)據(jù)庫返回Decimal模型直接把它當(dāng)float參與運(yùn)算。這些錯(cuò)誤不是單一模塊內(nèi)的類型錯(cuò)誤而是跨系統(tǒng)、跨語言邊界上的類型斷裂。在 AI 生成代碼的場景里由于模型一次只能看到有限上下文它很難意識到邊界的另一側(cè)是什么類型于是這種錯(cuò)誤特別高頻。識別了這些模式你就知道下一節(jié)要講的方法論為什么是必需的不能只依賴 LLM 的自覺必須用類型系統(tǒng)和 Schema 把它框住。4. Schema-First把類型系統(tǒng)變成 AI 的契約面對 LLM 生成代碼的不確定性當(dāng)前工程界公認(rèn)最有效的策略不是“提示詞寫得再詳細(xì)一點(diǎn)”而是Schema-First契約先行。它的核心思想是在讓模型生成代碼之前先把數(shù)據(jù)結(jié)構(gòu)、接口契約、類型定義用顯式的方式寫清楚并讓這些定義成為整個(gè)流程中不可繞過的約束。這里要引入另一個(gè)熱詞結(jié)構(gòu)化輸出Structured Output。幾乎所有主流 LLM API 現(xiàn)在都支持讓模型按 JSON Schema 返回結(jié)果。這個(gè)能力表面上只是為了“解析方便”實(shí)際上它做了一件極其重要的事把模型輸出從自由文本變成受約束的類型化數(shù)據(jù)。當(dāng)你在 API 調(diào)用里綁定一個(gè) JSON Schema 時(shí)模型要么輸出符合 Schema 的 JSON要么告訴你它做不到這本質(zhì)上就是一次“運(yùn)行時(shí)類型檢查”。同樣的邏輯也適用于代碼生成。與其讓 LLM 自由發(fā)揮寫一個(gè)內(nèi)部實(shí)現(xiàn)不如給它一個(gè)明確的類型簽名讓它只填充函數(shù)體// 業(yè)務(wù)接口已定義好LLM 只需要實(shí)現(xiàn)這個(gè)函數(shù) interface PriceCalculator { calculate(basePrice: number, discountRate: number): number; }當(dāng)類型簽名成為 AI 任務(wù)輸入的一部分模型就會被迫圍繞這個(gè)契約生成代碼而不是自己發(fā)明一個(gè)“更好”的接口。Schema-First 在工程上還有一個(gè)附帶價(jià)值可測試、可校驗(yàn)、可回滾。因?yàn)槠跫s是顯式的你可以對 AI 產(chǎn)出物做自動化驗(yàn)證。如果驗(yàn)證不通過要么讓模型重試要么標(biāo)記失敗走人工。這比“看一眼代碼感覺沒問題”靠譜得多。5. 實(shí)操示例一Python Pydantic 約束 LLM 輸出理論說完了下面用一個(gè)最小示例演示如何用 Pydantic 給 LLM 輸出加一道類型安全閘門。這個(gè)場景非常常見讓模型從一段文本里抽取結(jié)構(gòu)化信息然后寫進(jìn)數(shù)據(jù)庫或交給下游服務(wù)處理。5.1 環(huán)境準(zhǔn)備本文示例基于 Python 3.10 以上版本核心依賴如下。版本號請以你實(shí)際項(xiàng)目的鎖定版本為準(zhǔn)這里重點(diǎn)演示通用思路。pip install pydantic openai如果你用的不是 OpenAI 兼容接口換成 Anthropic、本地部署模型或其他 SDK 也一樣核心方法是通用的。5.2 定義輸出模型用一個(gè)數(shù)據(jù)類來描述我們期望的模型輸出結(jié)構(gòu)# 文件路徑schemas/order.py from datetime import datetime from typing import Literal from pydantic import BaseModel, Field, ValidationError class OrderInfo(BaseModel): order_id: str Field(description訂單號) amount: float Field(gt0, description訂單金額必須大于 0) currency: str Field(patternr^[A-Z]{3}$, descriptionISO 貨幣代碼例如 CNY、USD) status: Literal[pending, paid, cancelled] Field(description訂單狀態(tài)) paid_at: datetime | None Field(defaultNone, description支付時(shí)間未支付則為 null)這個(gè)模型做了幾件事amount: float并要求大于 0防止模型輸出負(fù)數(shù)或字符串金額。currency用正則約束必須是大寫三字母避免模型寫出人民幣這種無法解析的值。status用Literal限定取值范圍。paid_at可空防止模型隨意編造支付時(shí)間。5.3 調(diào)用 LLM 并做校驗(yàn)接下來調(diào)用模型并要求它返回 JSON然后用模型做解析校驗(yàn)# 文件路徑llm_order_parser.py import json from openai import OpenAI from schemas.order import OrderInfo, ValidationError client OpenAI(api_keysk-你的密鑰) # 生產(chǎn)環(huán)境請使用環(huán)境變量注入 prompt 從下面的訂單對話中提取訂單信息嚴(yán)格按照 JSON 格式返回 { order_id: 訂單號, amount: 金額數(shù)字, currency: 三位大寫貨幣代碼, status: pending/paid/cancelled 之一, paid_at: ISO 8601 時(shí)間或 null } 對話內(nèi)容用戶說已經(jīng)付款 299.9 元人民幣訂單號是 A12345。 resp client.chat.completions.create( modelgpt-4o-mini, # 以你實(shí)際可用的模型為準(zhǔn) messages[{role: user, content: prompt}], response_format{type: json_object}, # 部分接口支持按需開啟 ) raw json.loads(resp.choices[0].message.content) try: order OrderInfo.model_validate(raw) print(校驗(yàn)通過, order.model_dump()) except ValidationError as e: print(模型輸出不合法拒絕入庫) print(e.json())5.4 關(guān)鍵邏輯解釋model_validate(raw)這一步是全部流程的核心。它把模型輸出的自由 JSON 強(qiáng)制轉(zhuǎn)換成OrderInfo類型。如果模型少傳字段、傳錯(cuò)類型、金額為負(fù)數(shù)、狀態(tài)值不在枚舉里都會在這里拋出ValidationError。此時(shí)正確的處理不是“寬容地修一下再入庫”而是視為一次失敗生成記錄日志讓模型重試或進(jìn)入人工審核。這就是類型安全在大模型時(shí)代的具體形態(tài)你沒法保證模型不犯錯(cuò)但你可以保證錯(cuò)誤的產(chǎn)物到不了下游系統(tǒng)。運(yùn)行之后如果模型輸出正確你會看到類似校驗(yàn)通過 {order_id: A12345, amount: 299.9, ...}的結(jié)果。如果故意把提示詞改成“訂單金額是免費(fèi)”模型可能輸出amount0從而觸發(fā)gt0的校驗(yàn)失敗這正是我們想要的保護(hù)。6. 實(shí)操示例二TypeScript Zod 校驗(yàn) LLM 輸出Python 生態(tài)用 PydanticTypeScript 生態(tài)對應(yīng)的答案是 Zod。它們的思路一致先定義 Schema再校驗(yàn)外部數(shù)據(jù)。在 Node.js 服務(wù)里接入 LLM 時(shí)這種模式幾乎是標(biāo)配。6.1 安裝依賴npm install zod openai6.2 定義 Schema// 文件路徑src/schemas/analysis.ts import { z } from zod; export const AnalysisResult z.object({ topic: z.string().min(1).describe(分析主題), score: z.number().min(0).max(100).describe(主題匹配度0-100), tags: z.array(z.string()).max(10).describe(標(biāo)簽列表最多 10 個(gè)), summary: z.string().max(500).describe(不超過 500 字的總結(jié)), }); export type AnalysisResult z.infertypeof AnalysisResult;注意這里的describe方法。Zod 可以把 Schema 自動轉(zhuǎn)換成 JSON Schema而 JSON Schema 可以直接傳給支持結(jié)構(gòu)化輸出的 LLM 接口讓模型在生成階段就受到約束。這形成了一個(gè)很好的閉環(huán)同一個(gè) Schema 既用來約束模型輸出又用來校驗(yàn)實(shí)際返回。6.3 請求與校驗(yàn)// 文件路徑src/llm.ts import OpenAI from openai; import { AnalysisResult, AnalysisResult as AnalysisSchema } from ./schemas/analysis; const client new OpenAI({ apiKey: process.env.OPENAI_API_KEY }); export async function analyzeText(text: string): PromiseAnalysisResult { const resp await client.chat.completions.create({ model: gpt-4o-mini, messages: [ { role: user, content: 請分析下面文本的主題返回 JSON。文本${text}, }, ], response_format: { type: json_schema, json_schema: { name: analysis_result, schema: AnalysisSchema, // Zod 轉(zhuǎn)成的 JSON Schema strict: true, }, }, }); const content resp.choices[0]?.message.content; if (!content) { throw new Error(模型返回為空); } // 即使模型端做了約束這里仍然再做一次運(yùn)行時(shí)校驗(yàn) const parsed AnalysisResult.safeParse(JSON.parse(content)); if (!parsed.success) { console.error(LLM 輸出校驗(yàn)失敗, parsed.error.flatten()); throw new Error(模型輸出不滿足契約); } return parsed.data; }這段代碼體現(xiàn)了一個(gè)重要的工程原則不要在單一環(huán)節(jié)信任任何一方。哪怕模型端已經(jīng)配置了 JSON Schema 約束返回?cái)?shù)據(jù)也要safeParse一次。原因很簡單模型可能因?yàn)樯舷挛慕財(cái)喾祷貧埲?JSON可能返回空內(nèi)容可能在流式輸出時(shí)被中斷。運(yùn)行時(shí)校驗(yàn)是最后一道閘門閘門不能省。7. 知識庫與提示詞的類型化LLM Wiki 的啟示除了讓模型直接生成代碼另一個(gè)越來越常見的場景是把團(tuán)隊(duì)的領(lǐng)域知識、代碼規(guī)范、歷史決策整理成資料喂給 LLM 作為上下文。這個(gè)方向在社區(qū)里有個(gè)很有名的實(shí)踐就是所謂“LLM Wiki”的思路——用結(jié)構(gòu)化的 Markdown 知識庫來管理喂給模型的內(nèi)容。傳說中 Andrej Karpathy 分享的 LLM Wiki 工作流核心并不是“建一個(gè)維基”而是把知識寫成模型容易消費(fèi)的格式。這項(xiàng)工作看起來跟類型安全無關(guān)實(shí)際上關(guān)系極大。因?yàn)樘崾驹~里的概念定義不清晰本質(zhì)上是“語義層的類型不安全”。你在提示詞里寫了一個(gè)術(shù)語“訂單”但沒說明訂單有哪些字段、狀態(tài)有幾種、金額用什么單位模型就只能靠訓(xùn)練語料里的統(tǒng)計(jì)分布猜測。猜來猜去就產(chǎn)生了前面說的 API 幻覺、字段發(fā)明、邊界類型錯(cuò)誤。所以更準(zhǔn)確地說LLM Wiki 是給模型用的“類型定義文件”。比自然語言描述更可靠的形式是結(jié)構(gòu)化 Schema。下面是一個(gè) Agent 配置示例展示了如何把知識庫內(nèi)容也“類型化”# 文件路徑agents/order-assistant.yaml name: order_assistant description: 負(fù)責(zé)處理訂單查詢和售后申請的客服 Agent context_files: - docs/order-schema.md - docs/policy-refund.md knowledge_schema: order: fields: order_id: string amount: number currency: ISO_4217 status: enum[pending, paid, cancelled, refunded] created_at: ISO_8601 invariants: - amount 0 - refund 僅允許在 status paid 時(shí)發(fā)起 tools: - name: query_order params_schema: { order_id: string } returns_schema: { order: knowledge_schema.order }這份配置的價(jià)值在于它把模型完成任務(wù)所需的概念邊界用顯式的 Schema 描述出來了。模型不再需要“猜”訂單狀態(tài)有哪些取值配置里寫得清清楚楚Agent 框架也可以據(jù)此做參數(shù)校驗(yàn)調(diào)query_order之前先校驗(yàn)order_id格式。這跟 Pydantic/Zod 校驗(yàn)外部輸入是同一個(gè)道理只不過校驗(yàn)對象從模型輸出變成了模型使用的領(lǐng)域概念。從實(shí)踐效果看這種“顯式化”的做法有幾個(gè)直接收益。第一提示詞可以更短因?yàn)轭I(lǐng)域定義不在提示詞里反復(fù)粘貼而在配置文件里引用節(jié)省 Token 也減少前后矛盾。第二新人接手 AGent 配置時(shí)能快速理解系統(tǒng)邊界。第三配置本身可以納入代碼審查和版本管理任何類型定義的變更都有跡可循。如果你手上正好有一個(gè)經(jīng)常“亂說話”的 Agent不妨先檢查一下它的知識庫里到底有沒有清晰的概念定義而不是急著換更強(qiáng)的模型。8. 常見問題與排查思路到了實(shí)操階段你大概率會遇到下面這些狀況。我把高頻問題整理成一張排查表方便你直接對照處理。問題現(xiàn)象可能原因排查方向解決方案LLM 返回 JSON 解析失敗報(bào)Invalid JSON模型輸出被截?cái)嗷蛄魇巾憫?yīng)未完整拼接檢查原始 content 是否以}結(jié)尾開啟流式時(shí)拼接完整使用response_formatJSON 模式失敗重試Pydantic 報(bào)field required模型漏掉了必填字段查看 ValidationError 里缺失的字段名提示詞中給出樣例 JSON開啟結(jié)構(gòu)化輸出必要時(shí)做一輪修正重試金額字段被模型輸出為字符串Schema 聲明了 number 但模型未遵守檢查模型端是否支持 strict 模式在提示詞里寫明“amount 必須是 JSON number不要加引號”用 strict schema模型生成函數(shù)參數(shù)類型和調(diào)用處不匹配上下文窗口沒看到調(diào)用方代碼檢查傳給模型的上下文是否包含目標(biāo)類型定義讓模型先讀接口定義再生成實(shí)現(xiàn)用 TypeScript 強(qiáng)制編譯器兜底同一個(gè)需求多次生成接口風(fēng)格不一致LLM 每次都在“重新發(fā)明”數(shù)據(jù)結(jié)構(gòu)檢查是否提供了穩(wěn)定的類型簽名和示例固定 Schema 文件和示例代碼把已有實(shí)現(xiàn)作為 few-shot 示例Agent 反復(fù)調(diào)用工具失敗報(bào)參數(shù)錯(cuò)誤工具返回 Schema 與實(shí)際實(shí)現(xiàn)不一致檢查工具函數(shù)的運(yùn)行時(shí)校驗(yàn)日志用 Zod/Pydantic 校驗(yàn)工具參數(shù)工具側(cè)增加契約測試結(jié)構(gòu)化輸出請求報(bào)provider rejected the request schemaSchema 格式不被模型接口接受查看接口文檔確認(rèn) JSON Schema 版本和限制簡化 Schema避免過于復(fù)雜的嵌套和anyOf用 SDK 的 Schema 工具類生成模型輸出的字段值合法但語義錯(cuò)誤Schema 只能約束類型不能保證語義人工審視核心業(yè)務(wù)字段增加規(guī)則引擎或正則校驗(yàn)關(guān)鍵字段二次模型復(fù)核排查時(shí)有一條通用原則先確認(rèn)數(shù)據(jù)在哪個(gè)環(huán)節(jié)“變形”了。LLM 輸出鏈路通常經(jīng)過模型生成、JSON 解析、Schema 校驗(yàn)、業(yè)務(wù)使用四段。用日志把每段的數(shù)據(jù)快照打出來基本一眼就能定位是模型猜錯(cuò)了類型、還是解析代碼寫錯(cuò)了、還是校驗(yàn)規(guī)則定得太苛刻。不要在沒看原始輸出的情況下直接懷疑模型很多時(shí)候問題出在提示詞的表述歧義上。9. 最佳實(shí)踐與團(tuán)隊(duì)落地建議9.1 契約先行代碼生成排第二給 LLM 派代碼任務(wù)時(shí)先定義接口、數(shù)據(jù)結(jié)構(gòu)、異常邊界再讓模型實(shí)現(xiàn)內(nèi)部邏輯。這個(gè)順序不能反。如果讓模型先寫實(shí)現(xiàn)它大概率會自己發(fā)明一個(gè)“簡潔好用”但和其他模塊對不上的接口。契約先行之后代碼評審的重點(diǎn)也變了——Review 不再需要逐行看業(yè)務(wù)邏輯只需要重點(diǎn)檢查契約之外的部分。9.2 雙保險(xiǎn)生成時(shí)約束 運(yùn)行時(shí)校驗(yàn)這是整個(gè)流程里最重要的一條建議。生成時(shí)用 JSON Schema / 結(jié)構(gòu)化輸出約束運(yùn)行時(shí)用 Pydantic / Zod 再校驗(yàn)兩層不能相互替代。生成期約束減少無效輸出、省 Token運(yùn)行時(shí)校驗(yàn)保證“無論如何壞數(shù)據(jù)進(jìn)不了下游”。哪怕你的模型接口不支持結(jié)構(gòu)化輸出也一定要保留運(yùn)行時(shí)校驗(yàn)層。9.3 失敗重試要有限次LLM 輸出校驗(yàn)失敗后把錯(cuò)誤信息拼接進(jìn)提示詞讓模型重試一次是有用的做法。但要設(shè)置上限一般 2 到 3 次超過上限直接轉(zhuǎn)人工或標(biāo)記失敗。否則模型可能陷入“改一個(gè)錯(cuò)又引入另一個(gè)錯(cuò)”的循環(huán)既費(fèi) Token 又拖慢鏈路。9.4 為 AI 代碼建立專屬的 Review 流程大模型生成的代碼建議先跑自動化檢查再進(jìn)人工評審。自動化檢查包括編譯/類型檢查、Lint、單測、契約測試、Schema 校驗(yàn)。全部通過后才輪得到人。人工評審時(shí)重點(diǎn)關(guān)注模型最容易犯的三類問題安全邊界、異常處理、外部 API 調(diào)用的真實(shí)性。不要浪費(fèi)時(shí)間在格式和命名上這些交給工具。9.5 把 Schema 納入版本管理無論是 LLM 輸出的數(shù)據(jù)結(jié)構(gòu)、工具函數(shù)的參數(shù) Schema還是 Agent 的知識庫配置都應(yīng)該納入 Git 管理參與 Code Review。你會發(fā)現(xiàn)大多數(shù)“模型突然不聽話”的問題根源都是某個(gè) Schema 被悄悄修改或者知識庫文檔和實(shí)際代碼產(chǎn)生了漂移。9.6 用日志度量類型校驗(yàn)的失敗率建議在運(yùn)行時(shí)校驗(yàn)失敗時(shí)記錄結(jié)構(gòu)化日志字段包括模型、任務(wù)類型、錯(cuò)誤類型、缺失字段、重試次數(shù)。積累一段時(shí)間后你能看出模型在哪些任務(wù)上類型錯(cuò)誤率最高從而有的放矢地優(yōu)化提示詞或 Schema。沒有度量的 AI 工程基本等于盲飛。10. 總結(jié)與后續(xù)學(xué)習(xí)方向回到開頭的問題LLM 時(shí)代類型安全到底重不重要答案不是“重要”而是“比以往更重要且形態(tài)變了”。它不再只是編譯器替你檢查代碼錯(cuò)誤的機(jī)制而成了人和 AI 協(xié)作時(shí)的契約語言。類型系統(tǒng)負(fù)責(zé)把模型“大概差不多”的輸出翻譯成系統(tǒng)能夠安全消費(fèi)的確定結(jié)果。本文的核心結(jié)論可以濃縮成四句話LLM 對類型的理解是概率性的不能依賴它的“自覺”。Schema-First 是約束 AI 輸出的第一原則先定義契約再讓模型干活。生成時(shí)約束和運(yùn)行時(shí)校驗(yàn)必須雙管齊下任何單層信任都有風(fēng)險(xiǎn)。知識庫、提示詞、Agent 配置同樣需要“類型化”模糊的定義必然導(dǎo)致模糊的輸出。如果你剛開始在項(xiàng)目里引入這套思路我建議按這個(gè)順序?qū)嵺`第一步給現(xiàn)有的 LLM 輸出加上一層運(yùn)行時(shí)校驗(yàn)用 Pydantic 或 Zod 先把壞數(shù)據(jù)擋在門外第二步把常用的數(shù)據(jù)結(jié)構(gòu)和接口定義抽成 Schema 文件納入版本管理第三步在提示詞和知識庫中應(yīng)用同樣的顯式化原則讓模型從源頭少犯錯(cuò)。后續(xù)值得深入的方向有幾個(gè)一是學(xué)習(xí)函數(shù)調(diào)用Function Calling的 Schema 設(shè)計(jì)規(guī)范這是 Agent 工具與類型系統(tǒng)交匯最密集的領(lǐng)域二是關(guān)注主流 LLM 框架對結(jié)構(gòu)化輸出支持的演進(jìn)接口在快速變化三是研究一些大型代碼生成任務(wù)中的“類型引導(dǎo)生成”技術(shù)那已經(jīng)不是工程技巧而是研究課題了。對于大多數(shù)開發(fā)團(tuán)隊(duì)來說先把文章里的運(yùn)行時(shí)校驗(yàn)和契約先行落地就已經(jīng)能顯著降低 AI 編程的返工率。建議收藏備用等下次模型又給你寫出一個(gè)隱式any的時(shí)候再回來對照排查表看看。