中文 ▾
获取 API 密钥

LangChain 智能体 AI 文档:工具与 JSON 模式

大多数 LangChain 智能体 AI 文档假设使用供应商自己的模型类,但任何兼容 OpenAI 的接口在设置 base URL 后均可与 ChatOpenAI 配合使用。本指南将 LangChain 连接到此 API,并逐步构建一个支持工具调用的智能体。

更新于

要点

  • 使用 ChatOpenAI,将 base_url 设置为该 API,并将模型设置为 uncensored。
  • 支持函数调用和 JSON 模式,因此 bind_tools 和 response_format 按文档所述工作。
  • 限制智能体循环,验证工具参数,并在完整密钥下将 max_concurrency 保持在 8 或以下。
  • 通过 SSE 的流式输出会在末尾返回 token 使用情况,有助于你追踪每次智能体运行的成本。
机械臂在循环轨道上通过工具站搬运方块,代表 LangChain 智能体循环

开始前的准备工作

如果你正在阅读 LangChain 智能体 AI 文档,并想知道当模型不是示例中供应商提供的模型时会有什么变化,答案是几乎没有变化。LangChain 中的智能体是一个循环:模型读取对话,决定是否调用工具,你的代码执行该工具,然后将结果传回模型,直到生成最终答案。模型接口只需支持带函数调用的聊天补全,此 API 即支持。

你需要三样东西:来自 密钥页面的 API 密钥、Python 3.10 或更高版本,以及下面的包。基础 URL 是 https://api.unlimitedaiapi.com/v1,模型 ID 是 uncensored。这是一个由独立提供商运行的开放权重模型,因此没有模型列表可供选择;GET /v1/models 会返回该模型以供客户端发现。

pip install -U langchain langchain-openai
export UNLIMITED_API_KEY="your-key-here"

步骤 1:将 ChatOpenAI 连接到接口

LangChain 的 ChatOpenAI 类接受自定义的 base_url。它的其他所有方面保持不变,包括 invoke、stream、batch 和异步变体。

import os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="uncensored",
    base_url="https://api.unlimitedaiapi.com/v1",
    api_key=os.environ["UNLIMITED_API_KEY"],
    temperature=0.2,
)

print(llm.invoke("Reply with one short sentence.").content)

如果打印出一句话,则身份验证、路由和模型名称均正确。身份验证使用标准的 Authorization: Bearer 头,该类会自动为你添加。常见的错误是在 base URL 中遗漏了 /v1,这通常会导致第一次调用失败。

步骤 2:定义工具并绑定它们

工具是带有 docstring 的普通 Python 函数。docstring 和类型提示将成为模型看到的 schema,因此请像向新同事解释函数那样编写它们。

import os
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI

@tool
def get_order_status(order_id: str) -> str:
    '''Look up the status of an order by its ID, for example A100.'''
    return {"A100": "shipped", "A101": "processing"}.get(order_id, "not found")

llm = ChatOpenAI(
    model="uncensored",
    base_url="https://api.unlimitedaiapi.com/v1",
    api_key=os.environ["UNLIMITED_API_KEY"],
    temperature=0,
)
llm_with_tools = llm.bind_tools([get_order_status])

ai = llm_with_tools.invoke("Where is order A100?")
print(ai.tool_calls)

打印出的列表包含一个名为 get_order_status 的调用,以及诸如 {"order_id": "A100"} 之类的参数。在底层,LangChain 将你的函数作为 chat completions 请求中 tools 数组的一项发送,API 支持 tools、tool_choice 和流式 tool_calls。要强制调用工具,请将 tool_choice 传递给 bind_tools。

为什么温度要设低

智能体链式调用多次模型,因此一个格式错误的参数可能导致运行失败。0 到 0.2 的温度值使工具选择更具可重复性。如果你希望在最终回答步骤中获得更多样化的文本,请仅在该步骤提高温度。

步骤 3:运行智能体循环

自己编写循环需要十五行代码,并准确显示每一步发生的情况,这在出现问题时很有帮助。工具结果作为 ToolMessage 对象传回模型,在传输中变为 role: "tool" 消息。

import os
from langchain_core.messages import HumanMessage, ToolMessage
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI

@tool
def get_order_status(order_id: str) -> str:
    '''Look up the status of an order by its ID, for example A100.'''
    return {"A100": "shipped", "A101": "processing"}.get(order_id, "not found")

llm = ChatOpenAI(
    model="uncensored",
    base_url="https://api.unlimitedaiapi.com/v1",
    api_key=os.environ["UNLIMITED_API_KEY"],
    temperature=0,
)
tools = {"get_order_status": get_order_status}
llm_with_tools = llm.bind_tools(list(tools.values()))

messages = [HumanMessage("Where is order A100, and what about A101?")]
for _ in range(5):                      # hard cap on loop length
    ai = llm_with_tools.invoke(messages)
    messages.append(ai)
    if not ai.tool_calls:
        break
    for call in ai.tool_calls:
        result = tools[call["name"]].invoke(call["args"])
        messages.append(ToolMessage(content=str(result), tool_call_id=call["id"]))

print(ai.content)

注意range(5)。没有步数限制的智能体可能会在令人困惑的工具结果上无限循环,且每一轮都会消耗到目前为止整个对话的输入 token。5 对于简单任务来说是一个合理的上限;请有意地提高它。

使用预构建的智能体辅助函数

最近的 LangChain 版本提供了一个辅助函数来为你运行此循环。名称和导入路径在不同版本间有所变化,因此请根据已安装版本的文档确认它们。在当前的 1.x 版本中,它看起来像这样:

import os
from langchain.agents import create_agent
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI

@tool
def get_order_status(order_id: str) -> str:
    '''Look up the status of an order by its ID, for example A100.'''
    return {"A100": "shipped", "A101": "processing"}.get(order_id, "not found")

llm = ChatOpenAI(
    model="uncensored",
    base_url="https://api.unlimitedaiapi.com/v1",
    api_key=os.environ["UNLIMITED_API_KEY"],
    temperature=0,
)

agent = create_agent(llm, tools=[get_order_status], system_prompt="You are a concise support assistant.")
result = agent.invoke({"messages": [{"role": "user", "content": "Where is order A100?"}]})
print(result["messages"][-1].content)

当你想要标准模式时使用辅助函数,当你需要自定义停止规则、每步日志记录或希望在模型看到之前过滤的工具结果时使用手写循环。

使用 JSON 模式的结构化输出

智能体通常需要将数据交给其他代码处理,例如计划、分类或提取的字段列表。JSON 模式强制回复为有效的 JSON 对象。在 LangChain 中,你可以通过bind传递它:

import json
import os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="uncensored",
    base_url="https://api.unlimitedaiapi.com/v1",
    api_key=os.environ["UNLIMITED_API_KEY"],
    temperature=0,
)
json_llm = llm.bind(response_format={"type": "json_object"})

msg = json_llm.invoke(
    "Extract the city and country from: 'I moved to Lyon, France last spring.' "
    "Answer as JSON with the keys city and country."
)
print(json.loads(msg.content))

在提示词中提及 JSON 一词,并描述你期望的键,如示例所示。JSON 模式保证语法,但不保证你的 schema,因此仍需验证解析后的对象(例如使用 Pydantic)并处理缺失键的情况。

智能体运行的限制、流式输出与成本

智能体在短时间内进行多次调用,因此账户限制比简单聊天机器人更重要。完整密钥允许 8 个并发请求和每分钟 300 个请求。试用密钥允许 2 个和 60 个。如果你使用 batch 进行扇出或同时运行多个智能体,请在配置中限制并发:

import os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="uncensored",
    base_url="https://api.unlimitedaiapi.com/v1",
    api_key=os.environ["UNLIMITED_API_KEY"],
)
prompts = ["Name one prime number.", "Name one even number.", "Name one square number."]
answers = llm.batch(prompts, config={"max_concurrency": 8})
for a in answers:
    print(a.content)

在试用密钥上使用 2 而不是 8。对于交互式智能体,llm.stream(...) 会通过 SSE 返回生成的 token,并在流结束时返回使用情况数字。

成本很容易估算。一次 5 步的运行,平均每步 4,000 个输入 token 和 300 个输出 token,总共使用 20,000 个输入 token 和 1,500 个输出 token,在每 1M token 价格为 $0.15 和 $0.50 的情况下,每次运行成本为 $0.003 + $0.00075 = $0.00375。定价页面有费率,文档列出了请求参数和标头,包括用于追踪单个失败调用的X-Request-Id。

设计模型可用的工具

大多数智能体失败可追溯至工具,而非循环。以下规则有助于任何模型:

  • 保持每个工具的范围狭窄。名为 get_order_status 的工具比名为 database_query 且接受自由文本的工具效果更好。
  • 使用简单的参数类型:字符串、整数和短枚举。深层嵌套的对象会给模型提供更多出错的方式。
  • 返回简短、清晰的结果。一个将 50,000 个字符转储到对话中的工具会填满上下文窗口,并增加后续每一步的成本。
  • 以文本形式返回错误,例如 "order_id 必须看起来像 A100",而不是抛出导致运行结束的异常。

在扩大规模之前,使用 $0.50 试用额度对少量真实提示词测试智能体。新用户可以在密钥页面一键获取,有效期为 7 天。

首先检查的陷阱

  • 工具调用从未出现。 使 docstring 更具体,降低温度,或使用tool_choice强制调用。
  • 参数无效。 在工具内部进行验证并返回清晰的错误字符串,以便模型在下一步中自行纠正。
  • 上下文增长。 窗口包含回复在内共 100,000 个 token。在填满窗口之前截断旧的工具输出。

问答

哪个 LangChain 类与此 API 配合使用?

ChatOpenAI 来自 langchain-openai。将 base_url 设为 https://api.unlimitedaiapi.com/v1,模型设为uncensored,并将你的密钥作为 api_key 传入。

API 是否支持智能体的函数调用?

支持。它接受 tools 和 tool_choice 参数,返回 tool_calls(流式输出时同样支持),并将结果以 role 为 tool 的消息形式传回。

LangChain 能否通过此 API 解析结构化输出?

可以,通过 JSON 模式:将 response_format 设置为 json_object 类型。这能确保输出是合法的 JSON 格式,因此你需要自行验证字段。

我可以并发运行多少个智能体?

完整密钥允许 8 个并发请求和每分钟 300 次请求。试用密钥允许 2 个并发和每分钟 60 次请求。

只差一张表单,即可获得密钥

创建账户,复制密钥,更改基础 URL。这就是全部设置。

获取 API 密钥