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

本地自定义工具实战

这里以累加求和为例，演示完整的工具绑定与调用流程。

定义工具

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

注意： 函数必须有类型注解，文档字符串（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 时设置 tool_choice="any"。

工具调用流程

from langchain_core.messages import HumanMessage, SystemMessage, ToolMessage

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

# 2. 模型决定是否调用工具
ai_message = bound_llm.invoke(messages)
messages.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"])
        messages.append(
            ToolMessage(content=str(result), tool_call_id=tool_call["id"])
        )

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

关键点： ai_message 是经过框架整合的响应。如果模型决定调用工具，tool_calls 列表会包含名称、参数和 ID。必须使用 ToolMessage 包装结果并传入 tool_call_id，否则模型无法关联上下文。

第三方工具集成

以 Tavily 搜索为例，演示如何接入外部服务。

集成与多轮调用

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

# 多轮调用示例
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)

实际运行时，模型可能会先搜索，拿到结果后再分析生成回答，这就是多轮工具调用的价值。

结构化输出

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

1. Pydantic BaseModel（推荐）

这是最常用的方式，类型安全且支持验证。

定义模型

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

优点： IDE 有完整提示，自动校验数据，支持嵌套结构。

2. TypedDict

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

from typing import TypedDict, Annotated

class TestOutputDict(TypedDict):
    weather: Annotated[str, "详细天气情况"]
    city_name: Annotated[str, "城市名称"]

注意： TypedDict 不支持 Field()，需用 Annotated 添加描述。类型检查相对较弱。

3. JSON Schema

标准化格式，跨语言通用，适合系统对接。

import json

json_schema = {
    "title": "CityInfo",
    "description": "城市信息",
    "type": "object",
    "properties": {
        "city": {"type": "string", "description": "城市名称"},
        "weather": {"type": "string", "description": "当前天气"},
        "attractions": {"type": "array", "items": {"type": "string"}}
    },
    "required": ["city", "weather"]
}

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 typing import Literal

class PersonInfo(BaseModel):
    name: str
    age: int

class CityInfo(BaseModel):
    city: str
    population: int

class Response(BaseModel):
    type: Literal["person", "city"] = Field(description="响应类型")
    person: PersonInfo | None = Field(default=None)
    city: CityInfo | None = Field(default=None)

model = llm.with_structured_output(Response)
result = model.invoke("上海人口多少？")
if result.type == "city":
    print(result.city)

优势： 一个接口处理多种请求，灵活性高。

三大实际应用场景

场景 1：信息提取器

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

典型应用： 简历解析、合同条款提取、发票识别。

示例：简历信息提取

from pydantic import BaseModel, Field

class Education(BaseModel):
    school: str
    degree: str
    major: str

class ResumeInfo(BaseModel):
    name: str
    phone: str
    education: list[Education]
    skills: list[str]

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

print(f"姓名：{result.name}")
print(f"技能：{', '.join(result.skills)}")

关键： 自动化录入，格式统一，减少人工错误。

场景 2：提示词增强

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

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

示例：搜索意图理解

from typing import Literal

class SearchIntent(BaseModel):
    intent_type: Literal["informational", "transactional"]
    keywords: list[str]
    filters: dict[str, str]

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

if intent.intent_type == "transactional":
    # 根据结构化意图执行精准搜索
    search_params = {"category": "笔记本电脑", "price_range": intent.filters.get("price_range")}

关键： 意图明确化，避免答非所问。

场景 3：工具调用 + 结构化输出组合

智能决策 + 精准执行，AI 先分析再行动。

示例：智能天气助手

from langchain_tavily import TavilySearch

class WeatherResult(BaseModel):
    location: str
    temperature: str
    weather: str

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}, 温度：{result.temperature}")

关键： 流程清晰，每步可追溯，结果规范。

总结对比

选择建议：

• 需要类型灵活切换 → 可选结构化输出
• 固定数据提取 → Pydantic 模型
• 复杂嵌套结构 → JSON Schema 或嵌套 Pydantic
• 简单键值对 → TypedDict

官方文档参考：

• LangChain 官方文档
• Pydantic 文档