LangChain 实战：工具调用与结构化输出指南

工具调用（Tool Calling）

工具调用是 LangChain 的核心功能之一，允许 AI 模型调用外部函数或 API 来完成特定任务。

例如，当我们希望获取当前天气情况时，由于 LLM 无法获取实时信息，此时我们就可以借助工具，通过外部服务进行搜索完成查询：

再例如，当我们希望获取数据库表中的数据时，由于 LLM 无法直接获取表数据，此时我们就可以借助工具，通过与数据库交互完成查询：

1. Tool 创建的三种方式

直接用 @tool 装饰函数

最简单，适合小工具。

from langchain_core.tools import tool

@tool
def add(a: int, b: int) -> int:
    return a + b

用 @tool + 自定义参数结构（Pydantic）

参数更清晰，能写详细说明。

from pydantic import BaseModel
from langchain_core.tools import tool

class AddInput(BaseModel):
    a: int
    b: int

@tool(args_schema=AddInput)
def add(a: int, b: int) -> int:
    return a + b

继承 BaseTool 写类

最灵活，适合复杂或异步操作（比如调 API）。

from langchain_core.tools import BaseTool

class AddTool(BaseTool):
    name = "add"
    description = "Adds two numbers together."

    def _run(self, a: int, b: int):
        return a + b

2. 本地自定义工具

我们以一个简单的累加工具为例，演示从定义到绑定的完整流程。

定义工具

使用 @tool 装饰器定义一个本地工具：

from langchain_core.tools import tool

@tool
def sum_to_n(n: int) -> int:
    """计算从 0 累加到 n 的结果"""
    total = 0
    for i in range(n + 1):
        total += i
    return total

关键点：

• 使用 @tool 装饰器标记函数
• 函数必须有类型注解（n: int 和 -> int）
• 文档字符串（docstring）会被模型用来理解工具的功能

绑定工具到模型

from langchain.chat_models import init_chat_model

llm = init_chat_model(
    model="deepseek-chat",
    model_provider="deepseek",
    api_key="your-api-key",
    temperature=0.7,
    max_tokens=8192,
)
# 绑定工具
bound_llm = llm.bind_tools([sum_to_n])

关键点：

• bind_tools() 方法将工具绑定到模型
• 可以绑定多个工具：bind_tools([tool1, tool2, tool3])
• 当然我们也可以让模型强制调用工具，那就需要在绑定工具时，设置 tool_choice="any"，表示强制调用至少一个工具。

工具调用流程

from langchain_core.messages import HumanMessage, SystemMessage, ToolMessage

# 1. 构建用户消息
message = [
    SystemMessage(content="你是一个数学助手。当用户给你一个数字 n 时，使用 sum_to_n 工具计算从 0 累加到 n 的结果。"),
    HumanMessage(content="10"),
]

# 2. 模型决定是否调用工具
ai_message = bound_llm.invoke(message)
message.append(ai_message)

# 3. 执行工具调用
for tool_call in ai_message.tool_calls:
    if tool_call["name"] == "sum_to_n":
        result = sum_to_n.invoke(tool_call["args"])
        message.append(
            ToolMessage(content=str(result), tool_call_id=tool_call["id"])
        )

# 4. 获取最终回复
final_msg = bound_llm.invoke(message).content
print(final_msg)

工作流程图：

用户输入 → AI 分析 → 决定调用工具 → 执行工具 → 返回结果 → AI 生成最终回答

AI 响应结构解析

当模型决定调用工具时，ai_message 包含以下关键信息：

# ai_message 结构（经过 LangChain 框架整合）
{
    'content': '我来计算从 0 累加到 10 的结果。',
    'tool_calls': [
        {
            'name': 'sum_to_n',  # 工具名称
            'args': {'n': 10},   # 工具参数
            'id': 'call_00_xxx', # 调用 ID
            'type': 'tool_call'
        }
    ],
    'response_metadata': {
        'token_usage': {...},
        'model_name': 'deepseek-chat',
        'finish_reason': 'tool_calls'  # 表示模型决定调用工具
    }
}

重要提示：

• ai_message 是经过 LangChain 框架整合后的响应，不是模型的原始输出
• tool_calls 列表包含模型决定调用的所有工具
• 必须使用 ToolMessage 包装工具执行结果，并提供 tool_call_id

3. 第三方工具集成（Tavily 搜索）

集成第三方工具

from langchain_tavily import TavilySearch

# 创建 Tavily 搜索工具
tavily_tool = TavilySearch(
    max_results=4,
    tavily_api_key="your-tavily-api-key"
)
# 绑定到模型
bound_llm = llm.bind_tools([tavily_tool])

关键点：

• 第三方工具通常需要 API Key
• 参数名必须正确（如 tavily_api_key 而不是 api_key）

多轮工具调用

有时模型可能需要多次调用工具才能得到满意的结果：

message = [
    SystemMessage(content="你是一个天气助手。使用 tavily_search 工具搜索天气情况。"),
    HumanMessage(content="2026 年 3 月 2 日北京天气情况"),
]

# 工具调用循环（最多 3 轮）
max_rounds = 3
for round_num in range(1, max_rounds + 1):
    # 调用模型
    ai_message = bound_llm.invoke(message)
    message.append(ai_message)

    # 如果没有工具调用，说明得到最终答案了
    if not ai_message.tool_calls:
        print(ai_message.content)
        break

    # 执行工具调用
    for tool_call in ai_message.tool_calls:
        result = tavily_tool.invoke(tool_call["args"])
        tool_message = ToolMessage(
            content=str(result),
            tool_call_id=tool_call["id"]
        )
        message.append(tool_message)

工作流程：

第 1 轮：用户提问 → AI 调用搜索工具 → 获取搜索结果
第 2 轮：AI 分析结果 → 生成最终答案（不再调用工具）

实际输出示例

根据搜索结果，2026 年 3 月 2 日北京天气情况： 白天天气：阴天，大部分地区有小雪或雨夹雪，北风转南风 2-3 级，最高气温 5-6℃。 夜间天气：阴天，山区有小雪，南风转北风 1-2 级，最低气温 -1℃到 0℃。 特别预警：北京市气象台发布大雾黄色预警信号，夜间至次日上午能见度小于 1000 米。

结构化输出（Structured Output）

结构化输出允许模型返回符合特定格式的数据，而不是纯文本。这对于数据提取、API 响应生成等场景非常有用。

例如，可能希望将模型输出存储在数据库中，并确保输出符合数据库模式。这种需求激发了结构化输出的概念，其中可以指示模型使用特定的输出结构进行响应。

1. Pydantic BaseModel（推荐）

定义 Pydantic 模型

from pydantic import BaseModel, Field

class TestOutput(BaseModel):
    """城市信息的 Pydantic 模型"""
    test: str = Field(description="这个城市现在的详细天气情况，包括天气状况、温度、风力等")
    test2: str = Field(description="城市名称")
    test3: str = Field(description="在这个城市出生的一个著名名人，包括简短介绍")

关键点：

• 继承 BaseModel
• 使用 Field() 添加字段描述，帮助模型理解每个字段的含义
• 支持类型验证和数据校验

绑定结构化输出

from langchain_deepseek import ChatDeepSeek

llm_deepseek = ChatDeepSeek(
    model_name="deepseek-chat",
    api_key="your-api-key",
    base_url="https://api.deepseek.cn/v1",
)

# 绑定结构化输出
struct_output_model = llm_deepseek.with_structured_output(TestOutput)

# 调用模型
result = struct_output_model.invoke("上海")

# 访问结构化数据
print(f"天气：{result.test}")
print(f"城市：{result.test2}")
print(f"名人：{result.test3}")

输出示例

# 返回的是 Pydantic 对象
test='上海现在天气晴朗，温度 25°C，东南风 3-4 级，湿度 65%，空气质量良好'
test2='上海'
test3='姚明，中国著名篮球运动员，1980 年出生于上海，曾效力于 NBA 休斯顿火箭队'

优点：

• 类型安全，IDE 有完整的代码提示
• 自动数据验证
• 可以使用 Field() 添加详细描述
• 支持复杂的嵌套结构

缺点：

• 需要定义类

2. TypedDict

定义 TypedDict

from typing import TypedDict, Annotated

class TestOutputDict(TypedDict):
    """城市信息的字典类型"""
    weather: Annotated[str, "这个城市现在的详细天气情况，包括天气状况、温度、风力等"]
    city_name: Annotated[str, "城市名称"]
    famous_person: Annotated[str, "在这个城市出生的一个著名名人，包括简短介绍"]
    population: Annotated[int, "城市人口数量（万人）"]

关键点：

• TypedDict 不支持 Field()
• 使用 Annotated[类型，"描述"] 添加字段描述
• 支持不同类型（str, int, float, bool 等）

使用 TypedDict

# 绑定结构化输出
struct_output_model_dict = llm_deepseek.with_structured_output(TestOutputDict)

# 调用模型
result_dict = struct_output_model_dict.invoke("上海")

# 访问字典数据
print(f"天气：{result_dict['weather']}")
print(f"城市：{result_dict['city_name']}")
print(f"人口：{result_dict['population']} 万人")

输出示例

# 返回的是纯字典
{'city_name':'上海','weather':'上海现在天气晴朗，温度 18-25°C，东南风 3-4 级','population':2487,'famous_person':'姚明，中国著名篮球运动员，前 NBA 休斯顿火箭队球员'}

优点：

• 轻量级，返回纯字典
• 不需要定义复杂的类
• 可以使用 Annotated 添加描述

缺点：

• 类型检查较弱
• 不支持 Field() 的高级功能

3. JSON Schema

定义 JSON Schema

import json

json_schema = {
    "title": "CityInfo",
    "description": "城市信息的 JSON 格式",
    "type": "object",
    "properties": {
        "city": {"type": "string", "description": "城市名称"},
        "weather": {"type": "string", "description": "当前天气情况，包括温度、天气状况、风力"},
        "attractions": {
            "type": "array",
            "description": "城市的著名景点列表",
            "items": {"type": "string"}
        },
        "gdp": {"type": "number", "description": "城市 GDP（亿元）"}
    },
    "required": ["city", "weather", "attractions", "gdp"]
}

关键点：

• 使用标准的 JSON Schema 格式
• 支持复杂的嵌套结构（数组、对象等）
• required 字段指定必填项

使用 JSON Schema

# 绑定结构化输出
struct_output_model_json = llm_deepseek.with_structured_output(json_schema)

# 调用模型
result_json = struct_output_model_json.invoke("北京")

# 格式化输出
print(json.dumps(result_json, ensure_ascii=False, indent=2))

输出示例

{"city":"北京","weather":"晴，温度 15°C，风力 2 级","attractions":["故宫","天安门广场","长城","颐和园","天坛","圆明园"],"gdp":40269.6}

优点：

• 标准化，跨语言通用
• 支持复杂的嵌套结构
• 灵活，可以定义任意结构

缺点：

• 定义较繁琐
• 没有 IDE 类型提示
• 返回的是 dict，不是 JSON 字符串

4. 可选结构化输出（动态类型选择）

当你需要模型根据用户输入自动选择返回不同类型的结构化数据时，可以使用可选结构化输出。这在以下场景非常有用：

• 智能客服系统：根据用户问题返回不同类型的信息（人物、产品、订单等）
• 信息提取系统：从文本中提取不同类型的实体
• 多功能 API：一个接口根据请求返回不同格式的数据

实现方式

使用 Literal 类型和嵌套的 Pydantic 模型：

from pydantic import BaseModel, Field
from typing import Literal

# 定义不同的数据结构
class PersonInfo(BaseModel):
    """人物信息"""
    name: str = Field(description="姓名")
    age: int = Field(description="年龄")
    occupation: str = Field(description="职业")

class CityInfo(BaseModel):
    """城市信息"""
    city: str = Field(description="城市名称")
    population: int = Field(description="人口（万人）")

class NormalAnswer(BaseModel):
    """普通回答"""
    answer: str = Field(description="根据用户的提问正常答复的内容")

# 定义包装类，让模型选择返回类型
class Response(BaseModel):
    """响应结构，模型根据问题选择返回人物、城市信息或普通回答"""
    type: Literal["person", "city", "normal"] = Field(
        description="响应类型：person 表示人物，city 表示城市，normal 表示普通回答"
    )
    person: PersonInfo | None = Field(default=None, description="人物信息，仅当 type 为 person 时填充")
    city: CityInfo | None = Field(default=None, description="城市信息，仅当 type 为 city 时填充")
    normal: NormalAnswer | None = Field(default=None, description="普通回答，仅当 type 为 normal 时填充")

使用示例

from langchain_deepseek import ChatDeepSeek

llm = ChatDeepSeek(
    model_name="deepseek-chat",
    api_key="your-api-key",
    base_url="https://api.deepseek.cn/v1",
)

# 绑定结构化输出
model = llm.with_structured_output(Response)

# 测试 1：询问城市
result1 = model.invoke("上海")
if result1.type == "city":
    print(f"城市：{result1.city.city}")
    print(f"人口：{result1.city.population}万")

# 测试 2：普通问题
result2 = model.invoke("你是哪个模型")
if result2.type == "normal":
    print(f"回答：{result2.normal.answer}")

输出示例

测试 1（城市）： 类型：city 城市：上海 人口：2489 万

测试 2（普通问题）： 类型：normal 回答：我是 DeepSeek 最新版本的 AI 助手，由深度求索公司开发...

关键特性

1. Literal 类型：限定模型只能选择预定义的类型值
2. 可选字段：使用 | None 和 default=None 表示字段可选
3. 嵌套结构：不同的数据类型作为子结构嵌套在包装类中
4. 模型自主决策：AI 根据问题内容自动判断应该返回哪种结构

优势

• 灵活性高：一个接口处理多种类型的请求
• 类型明确：通过 type 字段清楚知道返回的数据类型
• 易于扩展：可以轻松添加更多类型（如 "product", "order" 等）
• 代码简洁：不需要多个不同的接口或函数

结构化输出的三大实际应用场景

场景 1：作为信息提取器 - 将非结构化文本转化为结构化数据

核心价值

结构化输出最直接的应用就是信息提取：将杂乱无章的文本数据转换为规范的结构化数据，便于存储、查询和分析。

典型应用

• 简历解析：从 PDF/Word 简历中提取姓名、联系方式、教育经历、工作经验
• 合同分析：提取合同中的关键条款、金额、日期、甲乙方信息
• 发票识别：从发票图片 OCR 文本中提取发票号、金额、税额、日期
• 新闻摘要：从新闻文章中提取标题、摘要、关键人物、时间地点

实现示例：简历信息提取

from pydantic import BaseModel, Field

class Education(BaseModel):
    """教育经历"""
    school: str = Field(description="学校名称")
    degree: str = Field(description="学位：本科、硕士、博士等")
    major: str = Field(description="专业")
    start_year: int = Field(description="入学年份")
    end_year: int = Field(description="毕业年份")

class WorkExperience(BaseModel):
    """工作经历"""
    company: str = Field(description="公司名称")
    position: str = Field(description="职位")
    start_date: str = Field(description="入职日期")
    end_date: str = Field(description="离职日期，如果是当前工作则为'至今'")
    responsibilities: list[str] = Field(description="主要职责列表")

class ResumeInfo(BaseModel):
    """简历信息"""
    name: str = Field(description="姓名")
    phone: str = Field(description="电话")
    email: str = Field(description="邮箱")
    education: list[Education] = Field(description="教育经历列表")
    work_experience: list[WorkExperience] = Field(description="工作经历列表")
    skills: list[str] = Field(description="技能列表")

# 使用示例
model = llm.with_structured_output(ResumeInfo)
resume_text = """
张三，电话：138****1234，邮箱：[email protected]
教育背景：
- 2015-2019 清华大学 计算机科学与技术 本科
- 2019-2021 清华大学 人工智能 硕士
工作经历：
- 2021.07-2023.06 字节跳动 算法工程师 负责推荐系统开发，优化点击率提升 20%
- 2023.07-至今 阿里巴巴 高级算法工程师 负责大模型应用开发
技能：Python, PyTorch, LangChain, 机器学习
"""

result = model.invoke(f"请从以下简历中提取信息：\n{resume_text}")

# 提取后的结构化数据可以直接存入数据库
print(f"姓名：{result.name}")
print(f"联系方式：{result.phone} / {result.email}")
print(f"教育经历：{len(result.education)} 条")
print(f"工作经历：{len(result.work_experience)} 条")
print(f"技能：{', '.join(result.skills)}")

实际输出： 姓名：张三 联系方式：138****1234 / [email protected] 教育经历：2 条 工作经历：2 条 技能：Python, PyTorch, LangChain, 机器学习

关键优势：

• 自动化数据录入：无需人工逐字段复制粘贴
• 格式标准化：统一的数据格式便于后续处理
• 提高准确性：AI 理解上下文，减少人工错误
• 可扩展性强：轻松添加新字段或修改提取规则

场景 2：作为提示词增强 - 帮助 AI 更好理解用户意图

核心价值

通过结构化输出，可以让 AI 先理解、再执行。将用户的模糊需求转换为明确的结构化指令，确保 AI 准确理解用户意图。

典型应用

• 搜索意图识别：理解用户搜索的真实意图（查询、购买、比较、学习）
• 任务分解：将复杂任务拆解为多个子任务
• 参数提取：从自然语言中提取 API 调用所需的参数
• 多轮对话管理：理解对话上下文和用户当前状态

实现示例：搜索意图理解

from pydantic import BaseModel, Field
from typing import Literal

class SearchIntent(BaseModel):
    """搜索意图分析"""
    intent_type: Literal["informational", "transactional", "navigational", "comparison"] = Field(
        description="意图类型：informational(查询信息)、transactional(购买交易)、navigational(导航访问)、comparison(对比比较)"
    )
    keywords: list[str] = Field(description="提取的关键词列表")
    filters: dict[str, str] = Field(description="筛选条件，如价格范围、品牌、地区等")
    urgency: Literal["low", "medium", "high"] = Field(description="紧急程度")
    clarification_needed: bool = Field(description="是否需要进一步澄清")
    suggested_questions: list[str] = Field(description="建议的澄清问题列表")

# 使用示例
model = llm.with_structured_output(SearchIntent)
user_query = "我想买个性价比高的笔记本电脑，预算 5000 左右，主要用来写代码"

# 第一步：理解用户意图
intent = model.invoke(f"分析以下用户需求：{user_query}")
print(f"意图类型：{intent.intent_type}")
print(f"关键词：{', '.join(intent.keywords)}")
print(f"筛选条件：{intent.filters}")
print(f"紧急程度：{intent.urgency}")

# 第二步：根据理解的意图执行精准搜索
if intent.intent_type == "transactional":
    # 执行购买导向的搜索
    search_params = {
        "category": "笔记本电脑",
        "price_range": intent.filters.get("price_range", ""),
        "keywords": intent.keywords,
        "sort_by": "price_performance_ratio"
    }
    print(f"\n执行搜索：{search_params}")
elif intent.clarification_needed:
    # 需要进一步澄清
    print(f"\n需要澄清的问题:")
    for q in intent.suggested_questions:
        print(f" - {q}")

实际输出： 意图类型：transactional 关键词：笔记本电脑，性价比，写代码，编程 筛选条件：{'price_range': '4000-6000', 'usage': '编程开发', 'priority': '性价比'} 紧急程度：medium 执行搜索：{ 'category': '笔记本电脑', 'price_range': '4000-6000', 'keywords': ['笔记本电脑', '性价比', '写代码', '编程'], 'sort_by': 'price_performance_ratio' }

关键优势：

• 意图明确化：将模糊需求转换为明确的结构化指令
• 减少误解：AI 先理解再执行，避免答非所问
• 提高准确性：基于结构化理解执行后续操作
• 可追溯性：清楚知道 AI 是如何理解用户需求的

场景 3：与 Tool 联合使用 - 结构化输出 + 工具调用的完美组合

核心价值

结构化输出与工具调用结合，可以实现智能决策 + 精准执行：AI 先分析需求并输出结构化决策，然后调用相应工具执行。

典型应用

• 智能助手：理解用户指令 → 决定调用哪些工具 → 执行并返回结果
• 自动化工作流：分析任务 → 规划步骤 → 依次调用工具完成
• 数据分析：理解分析需求 → 调用数据查询工具 → 结构化返回分析结果
• 多工具协作：一个任务需要多个工具配合完成

实现示例：智能天气助手（工具调用 + 结构化输出整合）

from langchain.chat_models import init_chat_model
from langchain_tavily import TavilySearch
from pydantic import BaseModel, Field

# 初始化模型
llm_tavily = init_chat_model(
    model="deepseek-chat",
    model_provider="deepseek",
    api_key="your-api-key",
    temperature=0.7,
    max_tokens=8192,
)

# 创建搜索工具
tavily_tool = TavilySearch(
    max_results=4,
    tavily_api_key="your-tavily-api-key"
)

# 定义结构化输出格式
class WeatherResult(BaseModel):
    """天气查询结果"""
    location: str = Field(description="地点")
    date: str = Field(description="日期")
    temperature: str = Field(description="温度范围")
    weather: str = Field(description="天气状况")
    wind: str = Field(description="风力风向")
    warning: str = Field(description="预警信息，如果没有则为'无'")

# 步骤 1：先绑定工具
bound_llm = llm_tavily.bind_tools([tavily_tool])

# 步骤 2：再绑定结构化输出
structured_llm = bound_llm.with_structured_output(WeatherResult)

# 步骤 3：直接调用，自动完成工具调用和结构化输出
result = structured_llm.invoke("2026 年 3 月 2 日北京天气情况")

# 输出结构化结果
print(f"地点：{result.location}")
print(f"日期：{result.date}")
print(f"温度：{result.temperature}")
print(f"天气：{result.weather}")
print(f"风力：{result.wind}")
print(f"预警：{result.warning}")

实际输出： 地点：北京 日期：2026 年 3 月 2 日 温度：-1℃到 6℃ 天气：阴天，有小雪或雨夹雪 风力：北风转南风 2-3 级，夜间南风转北风 1-2 级 预警：大雾黄色预警，能见度小于 1000 米

关键优势：

• 智能决策：结构化输出帮助 AI 理解需求并做出决策
• 精准执行：基于结构化决策调用合适的工具
• 结果规范：工具返回的数据再次结构化，便于使用
• 流程清晰：理解 → 决策 → 执行 → 返回，每步都可追溯

三大场景对比总结

场景	核心价值	主要用途	典型应用	技术特点
信息提取器	非结构化 → 结构化	数据提取与转换	简历解析、合同分析、发票识别	单向转换、数据标准化
提示词增强	模糊意图 → 明确指令	意图理解与澄清	搜索优化、任务分解、参数提取	双向交互、意图明确化
Tool 联合使用	智能决策 + 精准执行	复杂任务自动化	智能助手、自动化工作流、数据分析	多步骤、工具协作

选择建议

1. 需要类型灵活切换 → 使用可选结构化输出（choice_struct.py 模式）
2. 固定的数据提取 → 使用单一 Pydantic 模型
3. 复杂嵌套结构 → 使用 JSON Schema 或嵌套 Pydantic 模型
4. 简单键值对 → 使用 TypedDict

四种结构化输出方式对比总结

方式	优点	缺点	适用场景	返回类型
Pydantic BaseModel	类型安全、字段验证、IDE 支持好、可使用 Field	需要定义类	复杂数据结构、需要验证	Pydantic 对象
TypedDict	轻量级、返回纯字典、使用 Annotated 添加描述	类型检查较弱、不支持 Field	简单字典结构	dict
JSON Schema	标准化、跨语言、灵活、支持复杂嵌套	定义繁琐、无 IDE 提示	跨系统对接、复杂嵌套	dict
可选结构化输出	灵活性高、类型明确、易扩展、代码简洁	需要定义包装类	多类型动态响应	Pydantic 对象

参考资源

• LangChain 官方文档
• Pydantic 文档
• JSON Schema 规范
• Tavily API 文档