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 代理式 AI 文件,並想知道當模型不是來自範例中的供應商時會有什麼變化,答案是非常少。LangChain 中的代理是一個迴圈:模型讀取對話,決定是否呼叫工具,你的程式碼執行該工具,然後結果傳回模型,直到產生最終答案。模型端點只需支援帶有工具呼叫的聊天完成功能,而此 API 確實支援。
你需要三樣東西:來自 金鑰頁面的 API 金鑰、Python 3.10 或更新版本,以及下方的套件。Base 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 和 async 變體。
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 和型別提示會變成模型看到的結構描述,因此請像向新同事解釋該函式那樣撰寫它們。
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 模式保證語法,但不保證你的結構描述,因此仍請驗證解析後的物件(例如使用 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。這就是整個設定過程。