Định tuyến đa mô hình LangGraph: Kiểm tra qua Gateway cho luồng công việc của Agent

Định tuyến đa mô hình LangGraph trước hết là một bài toán thiết kế đồ thị và sau đó là một bài toán về gateway. Đồ thị quyết định loại công việc nào đang diễn ra, client của mô hình quyết định tuyến tương thích với OpenAI nào sẽ được gọi, và gateway sẽ chứng minh liệu mỗi lệnh gọi có tuân thủ các quy tắc về ngân sách, công cụ, thử lại, ghi nhật ký và điều kiện dừng hay không.

Flatkey phù hợp ở ranh giới gateway đó. Trang web công khai của nó hiển thị một tuyến trò chuyện tương thích với OpenAI tại https://router.flatkey.ai/v1/chat/completions, với một khóa duy nhất, khả năng hiển thị mức sử dụng, kiểm soát thanh toán và định tuyến mô hình ở cùng một nơi. Hướng dẫn này trình bày một thiết lập định tuyến đa mô hình LangGraph thực tế cho các luồng công việc của agent mà không giả định rằng mọi bí danh mô hình, hành vi công cụ hoặc tuyến dự phòng đã được xác thực trong tài khoản của bạn.

Câu trả lời nhanh cho định tuyến đa mô hình LangGraph

Một thiết lập định tuyến đa mô hình LangGraph an toàn sẽ tách việc định tuyến thành ba lớp.

Đừng ẩn định tuyến đa mô hình LangGraph bên trong một prompt dài. Hãy đặt chính sách vào các nút đồ thị, các cạnh điều kiện và các kiểm tra qua gateway mà nhóm của bạn có thể kiểm tra.

Tại sao định tuyến mô hình thuộc về ranh giới đồ thị

Hầu hết các ví dụ về LangGraph đều tập trung vào luồng điều khiển của đồ thị: trạng thái, nút, cạnh, công cụ và tính bền vững. Đó là điểm khởi đầu đúng đắn, nhưng các agent trong môi trường sản xuất cũng cần các ranh giới tuyến mà các nhóm nền tảng và tài chính có thể suy luận.

Sử dụng các tuyến ở cấp độ đồ thị khi luồng công việc có các hồ sơ chi phí, độ trễ hoặc rủi ro công cụ khác biệt rõ ràng:

Ranh giới đó là nơi Flatkey có thể giúp ích. Thay vì rải rác các khóa nhà cung cấp riêng biệt qua mỗi nút, mỗi tuyến có thể gọi một URL cơ sở API tương thích với OpenAI trong khi Flatkey duy trì khả năng hiển thị ở cấp độ gateway. Để biết thiết kế chính sách liền kề, hãy xem hướng dẫn của Flatkey về các kiểm soát gateway cho AI agent.

Kiểm tra nguồn trước khi bạn kết nối tuyến

Sử dụng tài liệu hiện hành và kiểm tra tài khoản trực tiếp trước khi coi các mẫu là mã sản xuất.

Đoạn mã dưới đây là một mẫu. Hãy chạy nó với các phiên bản langchain, langchain-openai, và langgraph hiện tại của bạn trước khi triển khai một chính sách định tuyến đa mô hình LangGraph.

Cấu hình các mô hình trò chuyện được hỗ trợ bởi Flatkey

Cài đặt các gói hiện tại trong môi trường chạy đồ thị của bạn.

pip install -U langgraph langchain langchain-openai

Giữ gốc API tách biệt với đường dẫn điểm cuối. Các client LangChain nên nhận URL cơ sở; client sẽ thêm đường dẫn Chat Completions cho các lệnh gọi trò chuyện tương thích với OpenAI.

FLATKEY_API_KEY=sk-fk-your-key
FLATKEY_BASE_URL=https://router.flatkey.ai/v1
FLATKEY_FAST_MODEL=your-fast-model-alias
FLATKEY_REASONING_MODEL=your-reasoning-model-alias
FLATKEY_TOOL_MODEL=your-tool-capable-model-alias

Sau đó, tạo các client mô hình rõ ràng cho mỗi tuyến.

import os
from langchain.chat_models import init_chat_model

BASE_URL = os.getenv("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1")
API_KEY = os.environ["FLATKEY_API_KEY"]

fast_model = init_chat_model(
    model=os.environ["FLATKEY_FAST_MODEL"],
    model_provider="openai",
    base_url=BASE_URL,
    api_key=API_KEY,
)

reasoning_model = init_chat_model(
    model=os.environ["FLATKEY_REASONING_MODEL"],
    model_provider="openai",
    base_url=BASE_URL,
    api_key=API_KEY,
)

tool_model = init_chat_model(
    model=os.environ["FLATKEY_TOOL_MODEL"],
    model_provider="openai",
    base_url=BASE_URL,
    api_key=API_KEY,
)

Đây là hình dạng hữu ích nhỏ nhất cho định tuyến đa mô hình LangGraph: mỗi tuyến có một client mô hình được đặt tên, nhưng tất cả các lệnh gọi đều sử dụng cùng một ranh giới gateway. Đừng cho rằng một bí danh mô hình hỗ trợ streaming hoặc công cụ chỉ vì một bí danh khác có hỗ trợ. Hãy kiểm tra từng tuyến riêng biệt.

Xây dựng một mẫu định tuyến LangGraph

Sử dụng một nút phân loại để ghi tuyến đường vào trạng thái. Sau đó, để các cạnh điều kiện quyết định nút nào sẽ chạy tiếp theo.

from typing import Annotated, Literal, TypedDict

from langchain_core.messages import AIMessage, BaseMessage
from langchain_core.tools import tool
from langgraph.graph import END, StateGraph
from langgraph.graph.message import add_messages


class RouteState(TypedDict):
    messages: Annotated[list[BaseMessage], add_messages]
    route: Literal["simple", "complex", "tools", "stop"]
    budget_cents: float
    errors: int
    tool_calls: int


@tool
def lookup_account_status(account_id: str) -> str:
    """Công cụ mẫu. Thay thế bằng tra cứu chỉ đọc thực tế của bạn."""
    return "active"


tool_ready_model = tool_model.bind_tools([lookup_account_status])


def choose_route(state: RouteState) -> dict:
    last_message = state["messages"][-1].content.lower()

    if state.get("budget_cents", 0) <= 0:
        return {"route": "stop"}
    if state.get("errors", 0) >= 2:
        return {"route": "stop"}
    if "lookup" in last_message or "account" in last_message:
        return {"route": "tools"}
    if len(last_message) > 600:
        return {"route": "complex"}
    return {"route": "simple"}


def simple_answer(state: RouteState) -> dict:
    return {"messages": [fast_model.invoke(state["messages"])]}


def complex_answer(state: RouteState) -> dict:
    return {"messages": [reasoning_model.invoke(state["messages"])]}


def tool_answer(state: RouteState) -> dict:
    if state.get("tool_calls", 0) >= 3:
        return {"messages": [AIMessage(content="Tool-call limit reached.")] }
    return {"messages": [tool_ready_model.invoke(state["messages"])]}


workflow = StateGraph(RouteState)
workflow.add_node("choose_route", choose_route)
workflow.add_node("simple_answer", simple_answer)
workflow.add_node("complex_answer", complex_answer)
workflow.add_node("tool_answer", tool_answer)

workflow.set_entry_point("choose_route")
workflow.add_conditional_edges(
    "choose_route",
    lambda state: state["route"],
    {
        "simple": "simple_answer",
        "complex": "complex_answer",
        "tools": "tool_answer",
        "stop": END,
    },
)
workflow.add_edge("simple_answer", END)
workflow.add_edge("complex_answer", END)
workflow.add_edge("tool_answer", END)

graph = workflow.compile()

Mẫu này giữ cho định tuyến đa mô hình LangGraph luôn rõ ràng. Người đánh giá có thể thấy lý do tại sao một yêu cầu được chuyển đến simple_answer, complex_answer, tool_answer, hoặc stop mà không cần phải thiết kế ngược một prompt.

Nút tool_answer ở trên xác minh tuyến mô hình có thể đề xuất các lệnh gọi công cụ. Nếu đồ thị của bạn cần thực thi các công cụ, hãy thêm một ToolNode của LangGraph hoặc trình thực thi của riêng bạn sau nút mô hình đó, sau đó định tuyến kết quả công cụ trở lại đồ thị với cùng các kiểm tra về ngân sách và điều kiện dừng.

Thêm các kiểm tra qua gateway xung quanh mỗi lệnh gọi mô hình

Tuyến đồ thị không nên là rào chắn bảo vệ duy nhất. Hãy thêm một trình bao bọc nhỏ để kiểm tra ngân sách trước một lệnh gọi mô hình và ghi lại bằng chứng sau một lệnh gọi mô hình.

from dataclasses import dataclass
from time import time


@dataclass
class GatewayDecision:
    route: str
    model_alias: str
    allowed: bool
    reason: str
    started_at: float


def preflight(route: str, model_alias: str, state: RouteState) -> GatewayDecision:
    if state.get("budget_cents", 0) <= 0:
        return GatewayDecision(route, model_alias, False, "budget_exhausted", time())
    if route == "tools" and state.get("tool_calls", 0) >= 3:
        return GatewayDecision(route, model_alias, False, "tool_limit_reached", time())
    if state.get("errors", 0) >= 2:
        return GatewayDecision(route, model_alias, False, "retry_limit_reached", time())
    return GatewayDecision(route, model_alias, True, "allowed", time())


def record_gateway_result(decision: GatewayDecision, response: BaseMessage) -> None:
    # Thay thế bằng ghi log có cấu trúc. Bao gồm nhãn khóa đã được biên tập,
    # tên tuyến, bí danh mô hình, dấu thời gian yêu cầu và siêu dữ liệu phản hồi.
    print(
        {
            "route": decision.route,
            "model_alias": decision.model_alias,
            "allowed": decision.allowed,
            "reason": decision.reason,
            "started_at": decision.started_at,
            "response_type": response.type,
        }
    )

Trong môi trường production, đừng chỉ dừng lại ở log cục bộ. Hãy đối chiếu dấu thời gian và bí danh mô hình với log sử dụng hoặc log yêu cầu của Flatkey. Đó là bằng chứng cho thấy định tuyến đa mô hình LangGraph đã sử dụng tuyến gateway mà bạn dự định.

Kiểm tra các công cụ trước khi bạn tin tưởng một tuyến sử dụng nhiều công cụ

Các node sử dụng nhiều công cụ xứng đáng có gói xác minh riêng. Một mô hình có thể giỏi trò chuyện thông thường nhưng lại không tương thích với schema công cụ của bạn, truyền phát các thay đổi (delta) của công cụ theo cách khác, hoặc tạo ra các đối số công cụ mà trình thực thi của bạn từ chối. Để kiểm tra khả năng tương thích sâu hơn, hãy sử dụng hướng dẫn của Flatkey về khả năng tương thích gọi công cụ giữa các nhà cung cấp.

Đây cũng là nơi bạn quyết định xem một tuyến có thuộc về Chat Completions hay Responses. Hãy giữ các họ endpoint riêng biệt; nếu bạn đang đánh giá các tuyến agent theo kiểu Responses, hãy kết hợp hướng dẫn này với bộ định tuyến API Responses tương thích OpenAI của Flatkey.

Chính sách thử lại, dự phòng và điều kiện dừng

Việc thử lại có thể che giấu các lỗi định tuyến. Một chính sách định tuyến đa mô hình LangGraph nghiêm ngặt nên quy định khi nào cần thử lại, khi nào cần dự phòng và khi nào cần dừng lại.

Middleware của LangChain có thể giúp với việc thử lại, dự phòng và giới hạn cuộc gọi ở cấp độ agent. Đối với các luồng công việc LangGraph được xây dựng thủ công, hãy giữ chính sách tương tự gần node gọi mô hình, sau đó chứng minh kết quả trong log của Flatkey.

Danh sách kiểm tra trước khi phát hành

Chạy các kiểm tra này trước khi đặt Flatkey làm tuyến mặc định cho một agent.

1. Gửi một yêu cầu curl trực tiếp đến https://router.flatkey.ai/v1/chat/completions với key và bí danh mô hình dự định.
2. Gọi mỗi client mô hình LangChain một lần bên ngoài LangGraph.
3. Chạy đồ thị với một prompt cho tuyến đơn giản, một cho tuyến phức tạp, và một cho tuyến sử dụng nhiều công cụ.
4. Buộc đi theo đường dẫn dừng bằng cách đặt budget_cents thành 0.
5. Buộc đạt giới hạn thử lại bằng cách đặt errors thành giá trị tối đa cho phép.
6. Xác nhận mỗi yêu cầu xuất hiện trong log của Flatkey với dấu thời gian, nhãn key, tên tuyến và bí danh mô hình mong đợi.
7. So sánh các trường chi phí hoặc sử dụng với người sở hữu phê duyệt ngân sách luồng công việc. Trang giá của Flatkey là nơi công khai phù hợp để bắt đầu việc xem xét đó.

Kết quả của danh sách kiểm tra này trở thành gói nghiệm thu cho định tuyến đa mô hình LangGraph. Nó hữu ích hơn một ảnh chụp màn hình của một prompt đang hoạt động vì nó chứng minh rằng đồ thị, client mô hình và gateway đều đồng thuận.

Xử lý sự cố định tuyến đa mô hình LangGraph

Nếu tuyến đầu tiên thất bại, hãy giữ phạm vi gỡ lỗi nhỏ: key, URL cơ sở, bí danh mô hình, một client mô hình, một node đồ thị, và một lần tra cứu log Flatkey.

Câu hỏi thường gặp

Định tuyến đa mô hình LangGraph có giống với chuyển đổi dự phòng của nhà cung cấp không?

Không. Định tuyến đa mô hình LangGraph quyết định tuyến nào phù hợp với nhiệm vụ trước hoặc trong khi thực thi đồ thị. Chuyển đổi dự phòng của nhà cung cấp là những gì xảy ra khi một tuyến đã chọn không thể hoàn thành. Bạn có thể sử dụng cả hai, nhưng chúng nên được kiểm tra riêng biệt.

Mỗi node LangGraph có nên sử dụng một mô hình khác nhau không?

Không. Hãy bắt đầu với hai hoặc ba tuyến đường rõ ràng. Quá nhiều bí danh mô hình (model alias) sẽ khiến việc xem xét nhật ký, ngân sách và khôi phục (rollback) trở nên khó khăn hơn.

Tôi có thể sử dụng Flatkey với cả hai tuyến Chat Completions và Responses không?

Flatkey cung cấp các họ điểm cuối (endpoint) tương thích với OpenAI, nhưng mỗi đường dẫn client vẫn cần được kiểm tra riêng. Hãy giữ các kiểm tra cho Chat Completions và Responses riêng biệt, đặc biệt là đối với các lệnh gọi công cụ (tool call), streaming, các trường sử dụng (usage field) và hành vi dự phòng (fallback).

Danh sách kiểm tra cuối cùng

Thiết lập định tuyến đa mô hình LangGraph của bạn đã sẵn sàng để vượt ra ngoài một mẫu (template) khi:

1. Tuyến đồ thị (graph route) hiển thị trong trạng thái và nhật ký.
2. Mỗi tuyến đường được ánh xạ tới một bí danh mô hình (model alias) đã được đặt tên.
3. Khóa Flatkey có thể gọi mỗi bí danh đã chọn thông qua URL cơ sở tương thích với OpenAI.
4. Các tuyến sử dụng nhiều công cụ (tool-heavy) vượt qua các bài kiểm tra về schema, đối số, giới hạn và lỗi.
5. Các điều kiện dừng về ngân sách và thử lại (retry) chạy trước một lệnh gọi mô hình khác.
6. Nhật ký sử dụng hoặc yêu cầu của Flatkey xác nhận tuyến đường đã chọn.
7. Việc khôi phục (Rollback) chỉ là một thay đổi cấu hình, không phải viết lại toàn bộ ứng dụng.

Khi bạn đã sẵn sàng định tuyến lưu lượng agent của LangGraph qua một gateway duy nhất, hãy lấy khóa Flatkey, bắt đầu với một tuyến đồ thị (graph route) có rủi ro thấp duy nhất, và chỉ mở rộng sau khi nhật ký chứng minh chính sách hoạt động hiệu quả.