LangChain v1.3.4 笔记 - 02 工具、结构化输出

工具

工具是为模型提供对外交互的方案之一(比如联网搜索,查询天气...),实际上是定义了输入和输出的函数,function calling | tool calling

在 langchain 中工具的声明遵循两种方案,基于 docstring 和装饰器。

py 复制代码
from langchain.tools import tool

@tool
def get_weather(local: str, days: int):
    """获取某地的指定天数的天气状况"""
    return f" {local} 未来 {days} 晴天"

# 可以直接使用 工具名.invoke 调用
res = get_weather.invoke({"local": "北京", "days": 2})

docstring

要遵循 Google 的注释规范

py 复制代码
@tool
def get_weather(local: str, days: int) -> str:
    """
    获取指定地点未来几天的状况

    Args:
        local (str): 地区
        days (int): 天数

    Returns:
        str: 天气状况
    """
    return f" {local} 未来 {days} 晴天"

Args | Returns 不是必须,存在之后更加友好。可以通过 convert_to_openai_tool 查看转换后的内容。

包括函数参数的名称、类型、以及返回值最后都会被解析为 json 丢给模型

py 复制代码
from langchain_core.utils.function_calling import convert_to_openai_tool

print(convert_to_openai_tool(get_weather))
# {
#     'type': 'function',
#     'function': {
#         'name': 'get_weather',
#         'description': '获取指定地点未来几天的状况\n\nArgs:\n    local (str): 地区\n    days (int): 天数\n\nReturns:\n    str: 天气状况',
#         'parameters': {
#             'properties': {
#                 'local': {'type': 'string'}, 
#                 'days': {'type': 'integer'}
#             }, 
#             'required': ['local', 'days'], 
#             'type': 'object'
#          }
#     }
# }

可以通过 parse_docstring 属性优化描述信息的展示

py 复制代码
@tool(parse_docstring=True)
def get_weather(local: str, days: int) -> str:
    pass
# {
#     'type': 'function',
#     'function': {
#         'name': 'get_weather',
#         'description': '获取指定地点未来几天的状况',
#         'parameters': {
#             'properties': {
#                 'local': {'description': '地区', 'type': 'string'}, 
#                 'days': {'description': '天数', 'type': 'integer'}
#             },
#             'required': ['local', 'days'],
#             'type': 'object'
#         }
#     }
# }

@tool

  • name_or_callable 默认属性,可以不按需传递,工具的名称;如果不指定则按照函数名
  • description 工具的描述
  • args_schema 工具的参数类型

与 docstring 可以共存,但参数大于注释

py 复制代码
@tool(name_or_callable="getWeather", description="获取指定地点未来几天的状况")
def get_weather(local: str, days: int) -> str:
    pass

args_schema

基于 pydantic 约束参数的类型,并且可以为每个参数增加对应的描述、默认值等数据

py 复制代码
from pydantic import BaseModel, Field
from typing import Literal

class User(BaseModel):
    username: str = Field(description='用户名')
    password: str = Field(description='密码')
    is_active: Literal['active', 'inactive'] = Field('active', description='是否激活')
    age: int | None = Field(None, description='年龄')

class Users(BaseModel):
    total: int
    data: list[User]


# 这个参数必须 Users 类型,否则就会校验失败
@tool(args_schema=Users)
def get_users(users: Users):
    """获取用户列表"""
    pass

print(convert_to_openai_tool(get_users))

# {
#     'type': 'function',
#     'function': {
#         'name': 'get_users',
#         'description': '获取用户列表',
          # 👉🏻 可以直接将对象的 value 做为 args_schema 的参数
          # 👉🏻 在动态工具的场景很常见
#         'parameters': {
#             'properties': {
#                 'total': {'type': 'integer'},
#                 'data': {
#                     'items': {
#                         'properties': {
#                             'username': {'description': '用户名', 'type': 'string'},
#                             'password': {'description': '密码', 'type': 'string'},
#                             'is_active': {'default': 'active', 'description': '是否激活', 'enum': ['active', 'inactive'], 'type': 'string'},
#                             'age': {'anyOf': [{'type': 'integer'}, {'type': 'null'}], 'default': None, 'description': '年龄'}
#                         },
#                         'required': ['username', 'password'],
#                         'type': 'object'
#                     },
#                     'type': 'array'
#                 }
#             },
#             'required': ['total', 'data'],
#             'type': 'object'
#         }
#     }
# }

args_schema 除了接收 pydantic 的对象也可以直接传递 json;就是通过 convert_to_openai_tool 转换之后的 parameters 的内容;

工具的调用

当下看工具的调用分为两种,模型调用、工具调用

py 复制代码
@tool
def get_weather(local: str) -> str:
    """获取指定地区的天气情况"""
    return f"{local} 天气晴朗"

# 工具调用 -> 杭州天气怎么样? 天气晴朗
print(get_weather.invoke("杭州天气怎么样?"))

# 工具调用 -> 通过 bind_tools 先绑定工具
model_with_tools = model.bind_tools([get_weather])
result = model_with_tools.invoke("杭州天气怎么样?")

rprint(result.pretty_print())
# ================================== Ai Message ==================================
# Tool Calls:
#   get_weather (call_00_fswh3fPohLjpQ3Arc24j4671)
#  Call ID: call_00_fswh3fPohLjpQ3Arc24j4671
#   Args:
#     local: 杭州

模型本身不能直接调用工具,所以仅返回了工具信息告知下一步需要怎么做

  • 模型将信息和工具组装好丢给模型;
  • 模型决定调用哪个工具丢给 agent;
  • agent 调用工具后拿到结果,在给模型;
  • 模型组织好信息,再给 agent,agent 再给用户组装好的信息。

langchain 提供了 create_agent 去完成上面的流程,当前还没有提及 可以通过自行构建 message 列表去实现类似的功能

py 复制代码
# 1. 用户问题
messages = [HumanMessage('杭州天气怎么样')]

# 2. 绑定工具,并且拿到需要调用的工具信息
model_with_tools = model.bind_tools([get_weather])
result = model_with_tools.invoke("杭州天气怎么样?")

# 3. 把 ai message 也塞进 list 中
messages.append(result)

# 4. 通过 ai message 拿到需要调用的工具
for tool_call in result.tool_calls:
    if tool_call["name"] == "get_weather":
        # 主动调用工具
        messages.append(get_weather.invoke(tool_call))

# 5. 打印整个对话流程
for message in messages:
    print(message.pretty_print())

tool_choice 工具使用策略

在通过 bind_tools 绑定工具的时候可以指定 tool_choice 属性控制模型使用工具的策略

  • none 不调用任何工具
  • required 必须调用一个或者多个工具
  • auto 模型自己抉择
  • <tool_name> 指定一个工具名,强制调用(这是 langchain 的规则,其他平时是对象)

大多数模型都支持这个参数,比如 kimi deepseek openai

预定义工具

langchain 中提供了一些预定义的工具可以直接使用,比如浏览器搜索等 预定义工具

以 Tavily Search 网页搜索为例

py 复制代码
# uv add langchain_tavily
from langchain_tavily import TavilySearch

# 会默认查找 TAVILY_API_KEY key, 需要自行去申请
tavily_search = TavilySearch(max_results=5, topic="general")

res = tavily_search.invoke("上海今天的天气怎么样?")

结构化输出

最简单的方案,不过于在 prompt 的最后一句,给 AI 来一句 "输出为 JSON 格式",万一 AI 抽风回复你:"好的,{"xx":"xx"}" 不就炸了

最好的方案是通过类型限制,然后结合 with_structured_output 绑定输出模式;

类型限制的方案包括 pydantic | TypedDict | json_schema | @dataclass

仅 pydantic 会返回构造对象,并且输出格式不对会出现校验错误,其余方案都只是返回字典且不会出现校验错误

pydantic

py 复制代码
from pydantic import BaseModel, Field, UUID4
from typing import Literal, Optional

class Active(str, Enum):
    ACTIVE = "active"
    INAVTIVE = "inactive"

class Info(BaseModel):
    phone: str = Field(description="手机号")
    email: Optional[str] = Field(description="邮箱") # 可选属性
    role: Literal["admin", "plain"] = Field("plain", description="角色") # 枚举属性

class User(BaseModel):
    id: UUID4 = Field(default_factory=uuid4, description="唯一 id", exclude=True)
    username: str = Field(description="账号")
    password: str = Field(description="密码")
    is_active: Active = Field("active", description="激活状态") # 枚举属性
    hobby: list[str] = Field(description="爱好")
    info: Info = Field(description="详情") # 嵌套属性

# 构造格式化输出的 model
structured_model = model.with_structured_output(User)
# 通过 model 获取格式化数据
result = structured_model.invoke([HumanMessage("生成一个用户数据")])

格式化的输出与模型有很强的关系

  • 直接使用 deepseek | kimi 模型需要关闭思考模式 extra_body={"thinking": {"type": "disabled"}}
  • 如果使用 openai:deepseek-chat 这种 model_provider 方案则会直接报错。这和 with_structured_output 中的 method 方案有关

接收三个参数 function_calling | json_schema | json_mode

  • function_calling 默认值,本质上也是将数据类型包装成工具交给模型去调用
  • json_schema 已知仅 openai 支持 response_format={"type": "json_schema"}
  • json_mode 使用此模式,提示中必须包含 json 字样,要求模型输出且不一定准确

使用 model_provider 出现错误的本质原因,就是 json_schema 是 openai 的默认方案,但是 deepseek 不支持这种方案,所以要手动指定参数 method="function_calling",如果直接使用 deepseek 则不存在这种问题

目前已知 kimi 需要和 deepseek 做一样的处理方案

with_structured_output 可以传递另一个参数 include_raw=True 会输出 AIMessage 内容包含解析后的数据,和是否解析错误的字段以及整个元数据

py 复制代码
structured_model = model.with_structured_output(User, include_raw=True, method="function_calling")
result = structured_model.invoke([HumanMessage("生成一个用户数据")])
# {
#     'raw': AIMessage(
#         content='',
#         additional_kwargs={'refusal': None},
#         response_metadata={
#             'token_usage': {
#                 'completion_tokens': 65,
#                 'prompt_tokens': 158,
#                 'total_tokens': 223,
#                 'completion_tokens_details': {
#                     'accepted_prediction_tokens': None,
#                     'audio_tokens': None,
#                     'reasoning_tokens': 1,
#                     'rejected_prediction_tokens': None
#                 },
#                 'prompt_tokens_details': None
#             },
#             'model_provider': 'openai',
#             'model_name': 'kimi-k2.6',
#             'system_fingerprint': None,
#             'id': 'chatcmpl-6a5736d5f296670ce7d01bb9',
#             'finish_reason': 'tool_calls',
#             'logprobs': None
#         },
#         id='lc_run--019f64ae-3118-7091-b119-9198e6b272c6-0',
#         tool_calls=[
#             {
#                 'name': 'User',
#                 'args': {
#                     'username': 'zhangsan',
#                     'password': 'aBc123!@#',
#                     'info': {'phone': '13800138000', 'email': 'zhangsan@example.com'},
#                     'hobby': ['篮球', '阅读', '旅游']
#                 },
#                 'id': 'User_0',
#                 'type': 'tool_call'
#             }
#         ],
#         invalid_tool_calls=[],
#         usage_metadata={'input_tokens': 158, 'output_tokens': 65, 'total_tokens': 223, 'input_token_details': {}, 'output_token_details': {'reasoning': 1}}
#     ),
#     'parsed': User(
#         id=UUID('d13ed36c-f20c-4920-99ca-3fd1614bded8'),
#         username='zhangsan',
#         password='aBc123!@#',
#         is_active='active',
#         hobby=['篮球', '阅读', '旅游'],
#         info=Info(phone='13800138000', email='zhangsan@example.com', role='plain')
#     ),
#     'parsing_error': None
# }

TypedDict

通过 Annotated 为字段注入元数据

py 复制代码
from typing import Literal, TypedDict, Annotated

class Info(TypedDict):
    phone: Annotated[str, '手机号']
    email: Annotated[str, '邮箱']
    role: Annotated[Literal['admin', 'plain'], '角色']

class User(TypedDict):
    account: Annotated[str, '账号']
    password: Annotated[str, '密码']
    info: Annotated[Info, '用户信息']

json_schema

py 复制代码
User = {
  "title": "",
  "description": "",
  "type": "object",
  "properties": {
    "account": {"type": "string", "description": "账号"},
    "password": {"type": "string", "description": "密码"},
  },
  "required": ["account", "password"]
}
# deepseek & kimi 不支持这种场景

@dataclass

py 复制代码
from pydantic import Field
from dataclasses import dataclass
from typing import Literal, Optional

@dataclass
class Info():
    phone: str = Field(description="手机号")
    email: Optional[str] = Field(description="邮箱")
    role: Literal["admin", "plain"] = Field("plain", description="角色")

@dataclass
class User():
    account: str = Field(description="账号")
    password: str = Field(description="密码")
    info: Info = Field(description="详情")
相关推荐
码事漫谈3 小时前
以后人人都可以成为导演
后端
Resean02234 小时前
Spring 源码分析(二)配置类的解析与扫描
java·后端·spring
一只爱撸猫的程序猿4 小时前
五周、两个开源仓库、九次拦截之后:AI 时代程序员缺的到底是什么
人工智能·后端·开源
北城笑笑5 小时前
Vue 110 ,若依SSE流式接口限次空500排查与解决
前端·javascript·vue.js·后端·vue
ServBay6 小时前
Local harness 将退役,VS Code 本地开发要不要搬到云端?
后端·ai编程·visual studio code
ashiho6 小时前
【LeetCode hot 100】3. 无重复字符的最长子串 (三种解法)
java·数据结构·后端·算法·leetcode·滑动窗口
张一凡937 小时前
你的 AGENTS.md,真的管到模型写代码了吗?
前端·后端·agent
00后程序员7 小时前
iOS 实时活动怎么开发,Windows 上用 KXBuild 和 ActivityKit 写灵动岛
后端·ios
程序员cxuan7 小时前
推荐 10 个 WorkBuddy 中的邪修用法
人工智能·后端·程序员
Bacon8 小时前
给项目做一次"全身 CT":Agent Skills 生态里的代码体检全链路
前端·人工智能·后端