OpenRouter ra mắt gói tích hợp LangChain: Hỗ trợ 400+ mô hình và tự động chuyển đổi dự phòng

Bạn muốn thêm hơn 400 mô hình của OpenRouter vào ứng dụng LangChain hiện có mà không cần xây dựng lại bất cứ thứ gì. Việc tích hợp hiện đã có một gói chuyên dụng: langchain-openrouter trên PyPI và @langchain/openrouter trên npm, nhưng nhiều hướng dẫn cũ vẫn dạy cách sử dụng ChatOpenAI cộng với việc ghi đè base_url. Hướng dẫn này bao gồm cách thực hiện hiện tại.

Khi bạn trỏ một chuỗi LangChain (LangChain chain) vào ChatOpenRouter, lớp định tuyến của chúng tôi sẽ tự động xử lý việc cân bằng tải nhà cung cấp, tránh sự cố và chuyển đổi dự phòng giữa các nhà cung cấp. Mã chuỗi của bạn không bao giờ thấy việc thử lại và một yêu cầu không hoàn thành sẽ không tốn phí của bạn. Tài liệu của LangChain bao gồm các tham số; hướng dẫn này cũng bao gồm hành vi định tuyến đằng sau chúng.

Khởi động nhanh: OpenRouter trong ứng dụng LangChain trong 5 phút

Thực hiện gọi mô hình hoạt động trong ba bước: cài đặt, xác thực, gọi hàm.

OpenRouter là một bộ định tuyến mô hình đằng sau một API tương thích với OpenAI: một endpoint, hơn 400 mô hình, hơn 70 nhà cung cấp. ChatOpenRouter khớp vào bất kỳ chuỗi hoặc tác nhân (agent) nào giống như bất kỳ mô hình trò chuyện LangChain nào khác. Chuỗi mô hình là phần duy nhất dành riêng cho OpenRouter.

Bước 1: Cài đặt và xác thực

Cài đặt langchain-openrouter và đặt khóa của bạn vào môi trường. Tạo khóa tại openrouter.ai/settings/keys.

Sử dụng cờ -U. Gói này đang ở bản beta và thay đổi nhanh chóng; hãy luôn cập nhật bản mới nhất. ChatOpenRouter tự động đọc OPENROUTER_API_KEY từ môi trường. Bạn cũng có thể truyền nó một cách rõ ràng dưới dạng api_key nếu bạn quản lý các bí mật theo cách khác.

Bước 2: Khởi tạo và gọi hàm

temperature, max_tokens và max_retries hoạt động chính xác như trên bất kỳ mô hình trò chuyện LangChain nào. Đối số model là slug của chúng tôi theo định dạng nhà cung cấp/mô hình (provider/model).

Nếu bạn muốn xác nhận khóa của mình hoạt động trước khi kết nối LangChain, endpoint này giao tiếp trực tiếp với định dạng OpenAI Chat:

Cùng một khóa, cùng một chuỗi mô hình, cùng một hình dạng phản hồi. ChatOpenRouter là một trình bao bọc LangChain có kiểu dữ liệu (typed wrapper) trên endpoint đó.

Bước 3: TypeScript

Đường dẫn TypeScript có cùng hình dạng với @langchain/openrouter:

Cài đặt bằng npm install @langchain/openrouter. Phiên bản hiện tại nằm trên npm.

Chi tiết thiết lập đầy đủ có trên trang tích hợp LangChain của OpenRouter và trong tài liệu tham khảo ChatOpenRouter của LangChain.

Chọn một mô hình: chuỗi nhà cung cấp/mô hình

Tham số model là slug của OpenRouter ở dạng nhà cung cấp/mô hình, và việc hoán đổi các mô hình chỉ là thay đổi một chuỗi. Không có gì khác trong chuỗi của bạn thay đổi: các lời nhắc (prompts), định nghĩa công cụ và đầu ra của bạn vẫn giữ nguyên.

Đặt model="anthropic/claude-sonnet-4.5" hôm nay, thay đổi nó thành openai/gpt-5-mini hoặc deepseek/deepseek-r1 vào ngày mai, và các chuỗi của bạn vẫn giữ nguyên như cũ.

Lấy các chuỗi nhà cung cấp/mô hình hiện tại từ openrouter.ai/models. Trang đó hiển thị những mô hình nào khả dụng, nhà cung cấp nào cung cấp chúng và mỗi mô hình tốn bao nhiêu chi phí cho mỗi token. Các slug trong hướng dẫn này chỉ là minh họa; danh mục là nguồn thông tin chính xác nhất.

Đối với các tác nhân LangChain, có một cách viết tắt bỏ qua hoàn toàn hàm khởi tạo:

Tiền tố openrouter:provider/model yêu cầu create_agent phân giải thông qua ChatOpenRouter. Cùng một thao tác hoán đổi một chuỗi, ở cấp độ cao hơn một lớp.

Phản hồi phát trực tuyến (Streaming)

Sử dụng stream_events để nhận các token khi mô hình tạo ra chúng. Biến thể bất đồng bộ, astream_events, thực hiện tương tự trong một chuỗi bất đồng bộ.

Phát trực tuyến có cùng mức phí trên mỗi token như một cuộc gọi không phát trực tuyến. Bạn phát trực tuyến để cải thiện trải nghiệm người dùng, không phải vì hóa đơn.

Truyền version="v3" để nhận lược đồ sự kiện hiện tại. Dạng bất đồng bộ cũng tương tự với astream_events và một vòng lặp async for:

usage_metadata khả dụng trên thông báo tổng hợp cuối cùng, vì vậy bạn có thể đọc số lượng token mà không cần thực hiện cuộc gọi thứ hai.

Gọi công cụ và đầu ra có cấu trúc

Sử dụng bind_tools để gọi công cụ và with_structured_output cho các phản hồi có kiểu dữ liệu. Cả hai đều chấp nhận strict=True để buộc tuân thủ lược đồ. strict hoạt động với các phương thức function_calling và json_schema, không hoạt động với json_mode.

Ràng buộc các công cụ với lược đồ Pydantic

strict=True khiến mô hình tuân thủ lược đồ công cụ thay vì tự ý tạo các đối số.

Nhận đầu ra có cấu trúc

with_structured_output ràng buộc một lược đồ vào toàn bộ phản hồi:

Phương thức mặc định là function_calling. Việc truyền method="json_schema" sử dụng thực thi JSON-schema gốc nơi mô hình hỗ trợ nó.

Không phải mọi mô hình đều hỗ trợ mọi phương thức; hãy kiểm tra danh mục mô hình để biết khả năng của từng mô hình. Việc đặt require_parameters: true trong đối tượng nhà cung cấp (sẽ được đề cập tiếp theo) giữ các yêu cầu trên các nhà cung cấp tôn trọng các tham số bạn đã gửi.

Định tuyến nhà cung cấp và dự phòng

ChatOpenRouter hiển thị lớp định tuyến của chúng tôi thông qua openrouter_provider và route, vì vậy một chuỗi duy nhất có thể tồn tại khi một nhà cung cấp bị sập mà không cần thêm mã dự phòng trong ứng dụng của bạn.

Đây là những gì xảy ra theo mặc định khi bạn thực hiện cuộc gọi. Chúng tôi cân bằng tải theo giá trên các nhà cung cấp phục vụ mô hình bạn đã chọn và định tuyến ra khỏi bất kỳ nhà cung cấp nào đã gặp sự cố trong 30 giây qua, sử dụng phần còn lại như các phương án dự phòng trực tiếp. Mã chuỗi của bạn không bao giờ thấy việc thử lại. Một yêu cầu cuối cùng không thể hoàn thành sẽ không bị tính phí.

Điều hướng nhà cung cấp với openrouter_provider