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

本地自定义工具实战

我们来看一个完整的本地工具流程，从定义到绑定再到执行。

1. 定义工具

使用 @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

2. 绑定工具到模型

通过 bind_tools() 方法将工具绑定到模型实例。如果需要强制模型调用工具，可以设置 tool_choice="any"。

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])

3. 工具调用流程

模型会先分析用户意图，决定是否调用工具。如果决定调用，我们需要手动执行工具并将结果反馈给模型。

from langchain_core.messages import HumanMessage, SystemMessage, ToolMessage

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

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

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

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

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

4. AI 响应结构解析

当模型决定调用工具时，ai_message 会包含关键信息，注意 tool_calls 列表里包含了工具名称、参数和调用 ID。

# ai_message 结构示例
{
    'content': '我来计算从 0 累加到 10 的结果。',
    'tool_calls': [
        {
            'name': 'sum_to_n',
            'args': {'n': 10},
            'id': 'call_00_xxx',
            'type': 'tool_call'
        }
    ],
    'response_metadata': {
        'token_usage': {...},
        'model_name': 'deepseek-chat',
        'finish_reason': 'tool_calls'
    }
}

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

集成第三方工具通常需要提供 API Key，并且要注意参数名的准确性。

1. 集成第三方工具

from langchain_tavily import TavilySearch

tavily_tool = TavilySearch(
    max_results=4,
    tavily_api_key="your-tavily-api-key"
)

bound_llm = llm.bind_tools([tavily_tool])

2. 多轮工具调用

有时模型可能需要多次调用工具才能拿到满意的结果，我们可以用一个循环来处理。

from langchain_core.messages import HumanMessage, SystemMessage, ToolMessage

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

max_rounds = 3
for round_num in range(1, max_rounds + 1):
    ai_message = bound_llm.invoke(messages)
    messages.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"]
        )
        messages.append(tool_message)

3. 实际输出示例

根据搜索结果，AI 会整合信息给出自然语言回答：

白天天气：阴天，大部分地区有小雪或雨夹雪，北风转南风 2-3 级，最高气温 5-6℃。 夜间天气：阴天，山区有小雪，最低气温 -1℃到 0℃。

结构化输出（Structured Output）

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

1. Pydantic BaseModel（推荐）

这是最稳妥的方式，支持类型验证和数据校验。

定义 Pydantic 模型

使用 Field() 添加字段描述，帮助模型理解每个字段的含义。

from pydantic import BaseModel, Field

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

绑定结构化输出

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.weather}")
print(f"城市：{result.city_name}")
print(f"名人：{result.famous_person}")

优点： 类型安全，IDE 有完整代码提示，自动数据验证，支持复杂的嵌套结构。

2. TypedDict

轻量级，返回纯字典，适合简单场景。

from typing import TypedDict, Annotated

class TestOutputDict(TypedDict):
    """城市信息的字典类型"""
    weather: Annotated[str, "这个城市现在的详细天气情况"]
    city_name: Annotated[str, "城市名称"]
    population: Annotated[int, "城市人口数量（万人）"]

struct_output_model_dict = llm_deepseek.with_structured_output(TestOutputDict)
result_dict = struct_output_model_dict.invoke("上海")

缺点： 类型检查较弱，不支持 Field() 的高级功能。

3. 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"]
}

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))

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

当你需要模型根据用户输入自动选择返回不同类型的结构化数据时，可以使用此模式。

from pydantic import BaseModel, Field
from typing import Literal

class PersonInfo(BaseModel):
    name: str = Field(description="姓名")
    age: int = 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="人物信息")
    city: CityInfo | None = Field(default=None, description="城市信息")
    normal: NormalAnswer | None = Field(default=None, description="普通回答")

model = llm_deepseek.with_structured_output(Response)
result1 = model.invoke("上海")
if result1.type == "city":
    print(f"城市：{result1.city.city}")

三大实际应用场景

场景 1：作为信息提取器

将非结构化文本转化为结构化数据，便于存储和分析。

典型应用： 简历解析、合同分析、发票识别。

from pydantic import BaseModel, Field

class Education(BaseModel):
    school: str = Field(description="学校名称")
    degree: str = Field(description="学位")

class ResumeInfo(BaseModel):
    name: str = Field(description="姓名")
    phone: str = Field(description="电话")
    education: list[Education] = Field(description="教育经历列表")

model = llm.with_structured_output(ResumeInfo)
resume_text = "张三，电话：138****1234..."
result = model.invoke(f"请从以下简历中提取信息：\n{resume_text}")

场景 2：作为提示词增强

帮助 AI 更好理解用户意图，将模糊需求转换为明确指令。

典型应用： 搜索意图识别、任务分解。

from pydantic import BaseModel, Field
from typing import Literal

class SearchIntent(BaseModel):
    intent_type: Literal["informational", "transactional", "navigational"] = Field(
        description="意图类型"
    )
    keywords: list[str] = Field(description="提取的关键词列表")

model = llm.with_structured_output(SearchIntent)
user_query = "我想买个性价比高的笔记本电脑，预算 5000 左右"
intent = model.invoke(f"分析以下用户需求：{user_query}")

场景 3：与 Tool 联合使用

结构化输出 + 工具调用的完美组合，实现智能决策 + 精准执行。

from langchain_tavily import TavilySearch
from pydantic import BaseModel, Field

class WeatherResult(BaseModel):
    location: str = Field(description="地点")
    temperature: str = Field(description="温度范围")
    weather: str = Field(description="天气状况")

tavily_tool = TavilySearch(max_results=4, tavily_api_key="your-key")
bound_llm = llm.bind_tools([tavily_tool])
structured_llm = bound_llm.with_structured_output(WeatherResult)

result = structured_llm.invoke("2026 年 3 月 2 日北京天气情况")
print(f"地点：{result.location}")

总结与建议

选择建议：

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

参考资源

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