企业级AI落地必备！LangGraph结构化输出技术图谱：5步构建可信赖智能体！

引言

在使用大语言模型进行开发时，我们经常需要模型返回特定格式的数据，而不是纯文本。比如在构建AI应用时，我们可能需要模型返回JSON格式的数据用于后续处理，或者返回符合特定数据结构的对象。这就是结构化输出的价值所在。

本文将深入探讨LangGraph中的结构化输出功能，重点介绍.with_structured_output()方法的使用，并通过实际代码示例展示如何在项目中应用这一技术。

什么是结构化输出？

结构化输出是指LLM（或LangGraph工作流中的其他节点）返回的输出被格式化为明确定义的、机器可读的对象，如字典、列表、自定义类或JSON对象，而不是纯文本。

对比示例：

• 非结构化输出："答案是北京。"
• 结构化输出：{"城市": "北京", "国家": "中国", "人口": 2154}

为什么需要结构化输出？

在LangGraph中，一个节点的输出通常作为另一个节点的输入。如果输出是结构化的，下一步就能准确知道期望什么字段/数据以及如何访问它们。这大大提高了系统的可靠性和可维护性。

核心技术：.with_structured_output()方法

.with_structured_output()是获得结构化输出的最简单、最可靠的方法。它专为那些原生支持结构化输出API（如工具/函数调用或JSON模式）的模型实现，并在后台使用这些功能。

基本工作原理

该方法接受一个模式作为输入，指定所需输出属性的名称、类型和描述。它返回一个类似于模型的Runnable，但输出的不是字符串或消息，而是对应于给定模式的对象。

实现方式详解

方式一：使用Pydantic类

使用Pydantic的主要优点是模型生成的输出将被验证。如果任何必需的字段缺失或任何字段的类型错误，Pydantic将抛出错误。

from pydantic import BaseModel, Field
from langchain_deepseek import ChatDeepSeek
from typing import Optional

# 定义Pydantic模型
classProductInfo(BaseModel):
"""产品基本信息"""

    name: str = Field(description="产品名称")
    price: float = Field(description="产品价格，单位为元")
    category: str = Field(description="产品所属类别")
    rating: Optional[int] = Field(
        default=None, description="产品评分，1-10分"
    )

# 初始化模型
llm = ChatDeepSeek(model="deepseek-chat")
structured_llm = llm.with_structured_output(ProductInfo)

# 调用示例
result = structured_llm.invoke("帮我分析一下iPhone 15这款手机")
print(result)
# 输出: ProductInfo(name='iPhone 15', price=5999.0, category='智能手机', rating=9)

方式二：使用TypedDict

如果您不想使用Pydantic验证，或者希望能够流式输出模型结果，可以使用TypedDict类定义模式。

from typing import Optional
from typing_extensions import Annotated, TypedDict

# 使用TypedDict定义模式
classStudentInfo(TypedDict):
"""学生基本信息"""

    name: Annotated[str, ..., "学生姓名"]
    age: Annotated[int, ..., "学生年龄"]
    major: Annotated[str, ..., "所学专业"]
    score: Annotated[Optional[float], None, "平均成绩，0-100分"]

structured_llm = llm.with_structured_output(StudentInfo)

result = structured_llm.invoke("张明，20岁，计算机科学专业，平均成绩85分")
print(result)
# 输出: {'name': '张明', 'age': 20, 'major': '计算机科学', 'score': 85.0}

方式三：使用JSON Schema

您也可以直接传入JSON Schema字典，这种方式不需要导入额外的类，但代码会更冗长一些。

json_schema = {
"title": "公司信息",
"description": "公司基本信息",
"type": "object",
"properties": {
"company_name": {
"type": "string",
"description": "公司名称",
        },
"industry": {
"type": "string",
"description": "所属行业",
        },
"employee_count": {
"type": "integer",
"description": "员工总数",
"default": None,
        },
    },
"required": ["company_name", "industry"],
}

structured_llm = llm.with_structured_output(json_schema)
result = structured_llm.invoke("分析一下腾讯公司")
print(result)
# 输出: {'company_name': '腾讯', 'industry': '互联网科技', 'employee_count': 110715}

LangGraph中的完整应用示例

下面是一个完整的LangGraph应用示例，展示如何在工作流中使用结构化输出：

import json
from pydantic import BaseModel, Field
from langchain_core.messages import HumanMessage, AIMessage
from langchain_deepseek import ChatDeepSeek
from langgraph.graph import StateGraph, MessagesState, END
from dotenv import load_dotenv

load_dotenv()

# 定义结构化输出模型
classAnalysisResult(BaseModel):
"""文本分析结果"""
    topic: str = Field(description="文本主要主题")
    summary: str = Field(description="内容摘要，不超过100字")
    keywords: list[str] = Field(description="提取的关键词列表")
    sentiment: str = Field(description="情感倾向：积极/消极/中性")

# 初始化模型
model = ChatDeepSeek(model="deepseek-chat")
structured_llm = model.with_structured_output(AnalysisResult).with_config(tags=["文本分析器"])

# 定义分析节点
defanalysis_node(state: MessagesState):
"""对输入文本进行结构化分析"""
    result = structured_llm.invoke(state["messages"])
    print(f"分析结果: {result}")

# 将分析结果转换为AIMessage
    response_content = f"""
📊 分析报告
主题: {result.topic}
摘要: {result.summary}
关键词: {', '.join(result.keywords)}
情感倾向: {result.sentiment}
    """.strip()

return {"messages": [AIMessage(content=response_content)]}

# 构建LangGraph工作流
workflow = StateGraph(MessagesState)
workflow.add_node("分析", analysis_node)
workflow.set_entry_point("分析")
workflow.add_edge("分析", END)

# 编译图
graph = workflow.compile()

# 测试用例
deftest_analysis():
"""测试文本分析功能"""
    test_text = """
    人工智能技术正在快速发展，特别是大语言模型的出现，
    为各个行业带来了前所未有的变革机会。从自动化客服到智能写作，
    从代码生成到数据分析，AI正在重塑我们的工作方式。
    虽然技术发展令人兴奋，但我们也需要关注AI伦理和安全性问题。
    """

    graph_input = {"messages": [HumanMessage(content=f"请分析以下文本：{test_text}")]}

# 运行分析
    result = graph.invoke(graph_input)
    print("="*50)
    print("最终输出:")
    print(result["messages"][-1].content)

# 执行测试
if __name__ == "__main__":
    test_analysis()

多模式选择

有时我们需要让模型在多个输出格式之间进行选择。最简单的方法是创建一个具有Union类型属性的父模式：

from typing import Union
from pydantic import BaseModel, Field

classJoke(BaseModel):
"""笑话内容"""
    setup: str = Field(description="笑话的铺垫部分")
    punchline: str = Field(description="笑话的笑点部分")
    rating: Optional[int] = Field(default=None, description="有趣程度，1-10分")

classConversationalResponse(BaseModel):
"""普通对话回应"""
    response: str = Field(description="对用户查询的对话式回应")

classFinalResponse(BaseModel):
"""最终输出，可以是笑话或普通回应"""
    final_output: Union[Joke, ConversationalResponse]

structured_llm = llm.with_structured_output(FinalResponse)

# 测试不同类型的输入
print("=" * 30)
print("请求笑话:")
result1 = structured_llm.invoke("给我讲个关于程序员的笑话")
print(result1)

print("=" * 30)
print("普通对话:")
result2 = structured_llm.invoke("你今天怎么样？")
print(result2)

流式输出支持

当输出类型是字典时（使用TypedDict类或JSON Schema定义时），我们可以从结构化模型中进行流式输出：

from typing_extensions import Annotated, TypedDict

classNewsSummary(TypedDict):
"""新闻摘要信息"""
    title: Annotated[str, ..., "新闻标题"]
    summary: Annotated[str, ..., "新闻摘要内容"]
    keywords: Annotated[list[str], ..., "新闻关键词"]

structured_llm = llm.with_structured_output(NewsSummary)

print("流式输出示例:")
for chunk in structured_llm.stream("总结今天的科技新闻"):
    print(chunk)

高级技巧

1. 原始输出处理

通过设置include_raw=True，可以获取原始输出，便于调试和错误处理：

structured_llm = llm.with_structured_output(AnalysisResult, include_raw=True)

result = structured_llm.invoke("分析人工智能发展")
print("原始输出:", result['raw'])
print("解析结果:", result['parsed'])
print("解析错误:", result['parsing_error'])

2. 指定输出方法

对于支持多种结构化输出方法的模型，可以通过method参数指定使用的方法：

# 使用JSON模式
structured_llm = llm.with_structured_output(AnalysisResult, method="json_mode")

最佳实践

1. 选择合适的模式类型：
2. • 需要运行时验证 → 使用Pydantic的BaseModel
   • 仅需静态类型检查 → 使用TypedDict
   • 需要流式输出 → 使用TypedDict或JSON Schema
3. 提供清晰的字段描述：字段的名称和描述对模型理解输出格式非常重要
4. 使用中文字段名：在中文应用场景中，使用中文字段名可以提高模型的理解准确性
5. 合理设置可选字段：使用Optional类型和默认值来处理不确定的信息

总结

结构化输出是现代AI应用开发中的重要技术。通过LangGraph的.with_structured_output()方法，我们可以轻松让大语言模型返回格式化的数据，提高应用的可靠性和可维护性。

无论是使用Pydantic进行严格的数据验证，还是使用TypedDict进行灵活的字典操作，或是直接使用JSON Schema，都能满足不同场景下的需求。关键是根据具体的应用场景选择最合适的实现方式。

在实际项目中，建议优先使用Pydantic方式，因为它提供了最好的类型安全和数据验证功能。对于需要流式输出的场景，则可以考虑使用TypedDict方式。

通过合理运用这些技术，我们可以构建更加健壮和高效的AI应用系统。

如何学习大模型 AI ？

我国在AI大模型领域面临人才短缺，数量与质量均落后于发达国家。2023年，人才缺口已超百万，凸显培养不足。随着Al技术飞速发展，预计到2025年，这一缺口将急剧扩大至400万，严重制约我国Al产业的创新步伐。加强人才培养，优化教育体系，国际合作并进，是破解困局、推动AI发展的关键。

但是具体到个人，只能说是：

“最先掌握AI的人，将会比较晚掌握AI的人有竞争优势”。

这句话，放在计算机、互联网、移动互联网的开局时期，都是一样的道理。

我在一线互联网企业工作十余年里，指导过不少同行后辈。帮助很多人得到了学习和成长。

我意识到有很多经验和知识值得分享给大家，也可以通过我们的能力和经验解答大家在人工智能学习中的很多困惑，所以在工作繁忙的情况下还是坚持各种整理和分享。但苦于知识传播途径有限，很多互联网行业朋友无法获得正确的资料得到学习提升，故此将重要的AI大模型资料包括AI大模型入门学习思维导图、精品AI大模型学习书籍手册、视频教程、实战学习等录播视频免费分享出来。

2025最新大模型学习路线

明确的学习路线至关重要。它能指引新人起点、规划学习顺序、明确核心知识点。大模型领域涉及的知识点非常广泛，没有明确的学习路线可能会导致新人感到迷茫，不知道应该专注于哪些内容。

对于从来没有接触过AI大模型的同学，我帮大家准备了从零基础到精通学习成长路线图以及学习规划。可以说是最科学最系统的学习路线。

针对以上大模型的学习路线我们也整理了对应的学习视频教程，和配套的学习资料。

大模型经典PDF书籍

新手必备的大模型学习PDF书单来了！全是硬核知识，帮你少走弯路！

配套大模型项目实战

所有视频教程所涉及的实战项目和项目源码等

博主介绍＋AI项目案例集锦

MoPaaS专注于Al技术能力建设与应用场景开发，与智学优课联合孵化，培养适合未来发展需求的技术性人才和应用型领袖。

这份完整版的大模型 AI 学习资料已经上传优快云，朋友们如果需要可以微信扫描下方优快云官方认证二维码免费领取【保证100%免费】

为什么要学习大模型？

2025人工智能大模型的技术岗位与能力培养随着人工智能技术的迅速发展和应用 ， 大模型作为其中的重要组成部分 ， 正逐渐成为推动人工智能发展的重要引擎 。大模型以其强大的数据处理和模式识别能力， 广泛应用于自然语言处理 、计算机视觉 、 智能推荐等领域 ，为各行各业带来了革命性的改变和机遇 。

适合人群

• 在校学生：包括专科、本科、硕士和博士研究生。学生应具备扎实的编程基础和一定的数学基础，有志于深入AGI大模型行业，希望开展相关的研究和开发工作。
• IT行业从业人员：包括在职或失业者，涵盖开发、测试、运维、产品经理等职务。拥有一定的IT从业经验，至少1年以上的编程工作经验，对大模型技术感兴趣或有业务需求，希望通过课程提升自身在IT领域的竞争力。
• IT管理及技术研究领域人员：包括技术经理、技术负责人、CTO、架构师、研究员等角色。这些人员需要跟随技术发展趋势，主导技术创新，推动大模型技术在企业业务中的应用与改造。
• 传统AI从业人员：包括算法工程师、机器视觉工程师、深度学习工程师等。这些AI技术人才原先从事机器视觉、自然语言处理、推荐系统等领域工作，现需要快速补充大模型技术能力，获得大模型训练微调的实操技能，以适应新的技术发展趋势。
  

课程精彩瞬间

大模型核心原理与Prompt：掌握大语言模型的核心知识，了解行业应用与趋势；熟练Python编程，提升提示工程技能，为Al应用开发打下坚实基础。

RAG应用开发工程：掌握RAG应用开发全流程，理解前沿技术，提升商业化分析与优化能力，通过实战项目加深理解与应用。

Agent应用架构进阶实践：掌握大模型Agent技术的核心原理与实践应用，能够独立完成Agent系统的设计与开发，提升多智能体协同与复杂任务处理的能力，为AI产品的创新与优化提供有力支持。

模型微调与私有化大模型：掌握大模型微调与私有化部署技能，提升模型优化与部署能力，为大模型项目落地打下坚实基础。

顶尖师资，深耕AI大模型前沿技术

实战专家亲授，让你少走弯路

一对一学习规划，职业生涯指导

• 真实商业项目实训
• 大厂绿色直通车

人才库优秀学员参与真实商业项目实训

以商业交付标准作为学习标准，具备真实大模型项目实践操作经验可写入简历，支持项目背调

大厂绿色直通车，冲击行业高薪岗位

文中涉及到的完整版的大模型 AI 学习资料已经上传优快云，朋友们如果需要可以微信扫描下方优快云官方认证二维码免费领取【保证100%免费】