LangChain 結構化輸出從入門到踩坑摘要結構化輸出讓 Agent 返回可預測的 JSON/Pydantic 模型而不是自然語言。本文深入解析 Provider Strategy 和 Tool Strategy 兩種策略附完整代碼和踩坑經驗。一、為什么會寫這篇最近在項目里做 Agent 開發(fā)遇到一個頭疼的問題大模型返回的內容格式飄忽不定有時候是 JSON有時候是純文本解析起來特別痛苦。后來發(fā)現(xiàn) LangChain 提供了**結構化輸出Structured Output**機制能讓 Agent 按照我們定義的格式返回數(shù)據(jù)。聽起來簡單實際踩了不少坑。門主這篇文章把結構化輸出的兩種策略講清楚順便把踩過的坑分享出來幫你少走彎路。二、什么是結構化輸出結構化輸出允許Agent以特定的、可預測的格式返回數(shù)據(jù)。這樣你無需解析自然語言響應就能獲得JSON 對象、Pydantic 模型或數(shù)據(jù)類dataclasses形式的結構化數(shù)據(jù)供應用程序直接使用。簡單說就是你定義好格式模型按格式返回。from pydantic import BaseModel, Fieldfrom langchain.agents import create_agentclass Answer(BaseModel): summary: str confidence: floatagent create_agent(modelopenai:gpt-5.5, response_formatAnswer)result agent.invoke({messages: [{role: user, content: 總結 AI 趨勢}]})# 直接拿到結構化對象print(result[structured_response]) # Answer(summary..., confidence...)三、響應格式類型LangChain 的create_agent通過response_format參數(shù)控制結構化輸出方式類型說明適用場景ToolStrategy通過工具調用實現(xiàn)結構化輸出所有支持工具調用的模型ProviderStrategy使用提供商原生結構化輸出OpenAI、Anthropic、xAI 等type[Schema]自動選擇最佳策略推薦寫法None不請求結構化輸出默認自動選擇邏輯四、提供商策略Provider Strategy4.1 原理部分模型提供商通過 API 原生支持結構化輸出如 OpenAI、xAI、Gemini、Anthropic。這是最可靠的方式。當模型支持原生結構化輸出時直接傳 Schema 類型即可自動啟用from pydantic import BaseModel, Fieldfrom langchain.agents import create_agentclass ContactInfo(BaseModel): 聯(lián)系人信息 name: str Field(description姓名) email: str Field(description郵箱) phone: str Field(description電話)# 自動選擇 ProviderStrategyagent create_agent( modelopenai:gpt-5.5, response_formatContactInfo)result agent.invoke({ messages: [{role: user, content: 提取聯(lián)系人張三, zhangsanexample.com, 13800138000}]})print(result[structured_response])# ContactInfo(name張三, emailzhangsanexample.com, phone13800138000)4.2 支持的 Schema 類型Schema 類型返回類型特點Pydantic ModelPydantic 實例支持字段驗證推薦Dataclassdict簡單輕量TypedDictdict類型提示友好JSON Schemadict靈活但無代碼提示4.3 嚴格模式ProviderStrategy支持strict參數(shù)啟用嚴格模式需要langchain1.2from langchain.agents.structured_output import ProviderStrategyagent create_agent( modelopenai:gpt-5.5, response_formatProviderStrategy(schemaContactInfo, strictTrue))門主提醒嚴格模式要求模型完全遵守 Schema部分國產模型可能不支持建議先測試再上線。五、工具調用策略Tool Strategy5.1 原理對于不支持原生結構化輸出的模型LangChain 通過工具調用實現(xiàn)結構化輸出。模型會假裝調用一個工具工具的參數(shù)就是結構化數(shù)據(jù)。這是兼容性最好的方式幾乎所有支持工具調用的模型都能用。5.2 基本用法from pydantic import BaseModel, Fieldfrom langchain.agents import create_agentfrom langchain.agents.structured_output import ToolStrategyfrom langchain.tools import tool# 定義輸出格式class WeatherStrategy(BaseModel): city: str Field(description城市名稱) weather: str Field(description天氣描述) temperature: str Field(description溫度) activity: str Field(description建議活動)# 定義工具tool(description查詢城市天氣的工具)def get_weather(city: str): return f今天{city}的天氣晴,溫度為30度,適合戶外活動# 創(chuàng)建 Agentagent create_agent( modelchanAI, tools[get_weather], response_formatToolStrategy(WeatherStrategy),)result agent.invoke({ messages: [{role: user, content: 長沙今天是什么天氣}]})print(result[structured_response])# WeatherStrategy(city長沙, weather晴, temperature30度, activity適合戶外活動)5.3 執(zhí)行流程六、自定義工具消息內容tool_message_content參數(shù)允許自定義生成結構化輸出時對話歷史中顯示的消息from langchain.agents.structured_output import ToolStrategyagent create_agent( modelchanAI, tools[get_weather], response_formatToolStrategy( schemaWeatherStrategy, tool_message_content天氣查詢已完成 ),)對比效果設置ToolMessage 內容不設置Returning structured response: {city: 長沙, ...}設置后天氣查詢已完成門主建議生產環(huán)境建議自定義方便日志排查和調試。七、錯誤處理模型在通過工具調用生成結構化輸出時可能會出錯。LangChain 提供了智能的重試機制。7.1 handle_errors 參數(shù)值行為True捕獲所有錯誤使用默認錯誤模板默認值str捕獲所有錯誤使用自定義消息type[Exception]只捕獲指定異常類型Callable[[Exception], str]自定義錯誤處理函數(shù)False不重試直接拋出異常7.2 完整示例from typing import Literalfrom pydantic import BaseModel, Field, field_validatorfrom langchain.agents import create_agentfrom langchain.agents.structured_output import ToolStrategyfrom langchain.tools import toolclass WeatherStrategy(BaseModel): city: str Field(description城市名稱) weather: str Field(description天氣) temperature: str Field(description溫度) activity: str Field(description建議活動) field_validator(city) classmethod def check_city(cls, value): # 模擬 Schema 校驗失敗 raise ValueError(故意觸發(fā) Schema 校驗失敗)tool(description查詢天氣)def get_weather(city: str): return f城市{city}\n天氣晴\n溫度30℃\n建議適合出去玩agent create_agent( modelchanAI, tools[get_weather], response_formatToolStrategy( schemaWeatherStrategy, tool_message_content天氣查詢完成, handle_errorsTrue # 開啟錯誤重試 ),)result agent.invoke({ messages: [{role: user, content: 長沙今天什么天氣}]})7.3 常見錯誤類型錯誤類型原因解決方案Schema 校驗失敗模型返回數(shù)據(jù)不符合 Schema檢查 Schema 定義開啟重試多次調用結構化輸出工具模型一次返回多個結構化數(shù)據(jù)LangChain 自動處理工具調用格式錯誤模型生成的 JSON 格式不正確使用更強大的模型八、多格式動態(tài)選擇不同問答不同 Schema實際項目中經常會遇到這種情況用戶問天氣 → 返回天氣格式用戶問聯(lián)系人 → 返回聯(lián)系人格式用戶問產品信息 → 返回產品格式總不能寫死一個 Schema 吧LangChain 提供了幾種方式解決這個問題。8.1 Union Types多 Schema 自動匹配ToolStrategy支持傳入Union類型模型會根據(jù)上下文自動選擇最合適的 Schemafrom pydantic import BaseModel, Fieldfrom typing import Literal, Unionfrom langchain.agents import create_agentfrom langchain.agents.structured_output import ToolStrategyclass ProductReview(BaseModel): 產品評價分析 rating: int | None Field(description產品評分 1-5, ge1, le5) sentiment: Literal[positive, negative] Field(description情感傾向) key_points: list[str] Field(description關鍵要點)class CustomerComplaint(BaseModel): 客戶投訴 issue_type: Literal[product, service, shipping, billing] Field(description問題類型) severity: Literal[low, medium, high] Field(description嚴重程度) description: str Field(description問題描述)class WeatherInfo(BaseModel): 天氣信息 city: str Field(description城市) weather: str Field(description天氣狀況) temperature: str Field(description溫度)# 多個 Schema 聯(lián)合模型自動選擇agent create_agent( modelchanAI, toolstools, response_formatToolStrategy(Union[ProductReview, CustomerComplaint, WeatherInfo]))# 模型會根據(jù)用戶問題自動匹配合適的 Schemaresult1 agent.invoke({messages: [{role: user, content: 分析這個評價質量很好5星推薦}]})# → ProductReview(rating5, sentimentpositive, key_points[質量很好])result2 agent.invoke({messages: [{role: user, content: 長沙今天天氣怎么樣}]})# → WeatherInfo(city長沙, weather晴, temperature25°C)執(zhí)行流程8.2 運行時動態(tài)切換 Schema如果需要更靈活的控制可以在不同場景下創(chuàng)建不同的 Agent 實例from langchain.agents import create_agentfrom langchain.agents.structured_output import ToolStrategy# 定義多個 Schemaclass WeatherSchema(BaseModel): city: str Field(description城市) temperature: str Field(description溫度) weather: str Field(description天氣)class ContactSchema(BaseModel): name: str Field(description姓名) phone: str Field(description電話) email: str Field(description郵箱)class OrderSchema(BaseModel): order_id: str Field(description訂單號) status: str Field(description訂單狀態(tài)) amount: float Field(description金額)# 工廠函數(shù)根據(jù)場景創(chuàng)建不同 Agentdef create_agent_by_scene(scene: str): scene_config { weather: { schema: WeatherSchema, system_prompt: 你是天氣查詢助手, tool_message_content: 天氣查詢完成 }, contact: { schema: ContactSchema, system_prompt: 你是聯(lián)系人管理助手, tool_message_content: 聯(lián)系人信息提取完成 }, order: { schema: OrderSchema, system_prompt: 你是訂單查詢助手, tool_message_content: 訂單查詢完成 } } config scene_config.get(scene, scene_config[weather]) return create_agent( modelchanAI, response_formatToolStrategy( schemaconfig[schema], tool_message_contentconfig[tool_message_content] ), system_promptconfig[system_prompt] )# 使用示例weather_agent create_agent_by_scene(weather)contact_agent create_agent_by_scene(contact)8.3 根據(jù)用戶意圖動態(tài)路由更智能的做法是先識別用戶意圖再路由到對應的 Agentfrom pydantic import BaseModel, Fieldfrom typing import Literalclass IntentSchema(BaseModel): 用戶意圖識別 intent: Literal[weather, contact, order, other] Field(description用戶意圖) extracted_info: str Field(description提取的關鍵信息)def smart_route(user_input: str): # 先用輕量模型識別意圖 intent_agent create_agent( modelchanAI, response_formatIntentSchema ) intent_result intent_agent.invoke( {messages: [{role: user, content: user_input}]} ) intent intent_result[structured_response].intent # 根據(jù)意圖路由到對應 Agent agent create_agent_by_scene(intent) return agent.invoke( {messages: [{role: user, content: user_input}]} )# 使用result smart_route(幫我查一下北京的天氣)8.4 對比總結方式優(yōu)點缺點適用場景Union Types簡單一行代碼模型可能選錯 SchemaSchema 數(shù)量少差異明顯工廠模式清晰可控需要預設場景場景固定數(shù)量有限意圖路由最靈活可擴展多一次模型調用復雜場景Schema 數(shù)量多門主建議如果 Schema 不超過 5 個直接用 Union 就行。場景很多的話上意圖路由更穩(wěn)。九、兩種策略對比維度Provider StrategyTool Strategy可靠性?????????兼容性僅支持原生輸出的模型所有支持工具調用的模型性能更快一次調用可能需要多次調用Schema 復雜度支持復雜 Schema同樣支持錯誤處理提供商處理LangChain 自動重試推薦場景OpenAI/Anthropic 等國產模型/開源模型十、實戰(zhàn)代碼完整示例10.1 基礎示例古詩生成from langchain_openai import ChatOpenAIfrom langchain.agents import create_agentfrom pydantic import BaseModel, Fieldfrom langchain.agents.structured_output import ToolStrategyimport dotenvdotenv.load_dotenv()chanAI ChatOpenAI( modelqwen3.7-plus, temperature0.7, extra_body{enable_thinking: False})class PoemStrategy(BaseModel): name: str Field(description古詩名稱) content: str Field(description古詩內容)agentChat create_agent( modelchanAI, response_formatPoemStrategy,)result agentChat.invoke({ messages: [ {role: system, content: 你是一個古詩創(chuàng)作助手}, {role: user, content: 今天長沙的天氣如何} ]})print(result[structured_response])# PoemStrategy(name長沙今日即景, content湘水悠悠繞古城...)10.2 進階示例帶工具的天氣查詢from langchain.tools import toolfrom langchain.agents.structured_output import ToolStrategyclass WeatherStrategy(BaseModel): city: str Field(description城市名稱) weather: str Field(description天氣描述) temperature: str Field(description溫度) activity: str Field(description建議活動)tool(description查詢城市天氣的工具)def get_weather(city: str): return f今天{city}的天氣晴,溫度為30度,適合戶外活動agentChat create_agent( modelchanAI, tools[get_weather], response_formatToolStrategy( schemaWeatherStrategy, tool_message_content天氣查詢已完成, handle_errorsTrue ),)result agentChat.invoke({ messages: [{role: user, content: 長沙今天是什么天氣}]})print(result[structured_response])# WeatherStrategy(city長沙, weather晴, temperature30度, activity適合戶外活動)學AI大模型的正確順序千萬不要搞錯了2026年AI風口已來各行各業(yè)的AI滲透肉眼可見超多公司要么轉型做AI相關產品要么高薪挖AI技術人才機遇直接擺在眼前有往AI方向發(fā)展或者本身有后端編程基礎的朋友直接沖AI大模型應用開發(fā)轉崗超合適就算暫時不打算轉崗了解大模型、RAG、Prompt、Agent這些熱門概念能上手做簡單項目也絕對是求職加分王給大家整理了超全最新的AI大模型應用開發(fā)學習清單和資料手把手幫你快速入門學習路線:?大模型基礎認知—大模型核心原理、發(fā)展歷程、主流模型GPT、文心一言等特點解析?核心技術模塊—RAG檢索增強生成、Prompt工程實戰(zhàn)、Agent智能體開發(fā)邏輯?開發(fā)基礎能力—Python進階、API接口調用、大模型開發(fā)框架LangChain等實操?應用場景開發(fā)—智能問答系統(tǒng)、企業(yè)知識庫、AIGC內容生成工具、行業(yè)定制化大模型應用?項目落地流程—需求拆解、技術選型、模型調優(yōu)、測試上線、運維迭代?面試求職沖刺—崗位JD解析、簡歷AI項目包裝、高頻面試題匯總、模擬面經以上6大模塊看似清晰好上手實則每個部分都有扎實的核心內容需要吃透我把大模型的學習全流程已經整理好了抓住AI時代風口輕松解鎖職業(yè)新可能希望大家都能把握機遇實現(xiàn)薪資/職業(yè)躍遷這份完整版的大模型 AI 學習資料已經上傳CSDN朋友們如果需要可以微信掃描下方CSDN官方認證二維碼免費領取【保證100%免費】