OpenRouter API Production Checklist

Xác minh khả năng tương thích API và các điểm cuối

Sử dụng các endpoint tương thích chuẩn với OpenAI để tích hợp đáng tin cậy.

Điểm cuối chính là POST /v1/chat/completions. Điều này xử lý việc tạo văn bản cho lịch sử trò chuyện. Một điểm cuối thứ hai, GET /v1/models, liệt kê các mô hình có sẵn. Bạn không cần các điểm cuối nhúng hoặc tạo hình ảnh cho các nhiệm vụ chỉ bằng văn bản. Nhiều nhà phát triển giả định rằng họ cần một lớp định tuyến phức tạp. OpenRouter đơn giản hóa điều này bằng cách cung cấp một điểm truy cập duy nhất. Bạn gửi một tải trọng JSON với ID mô hình và lời nhắc hệ thống của bạn. Dịch vụ trả về JSON có cấu trúc với nội dung và dữ liệu sử dụng. Thiết kế này phù hợp với kỳ vọng của SDK OpenAI chính thức. Bạn có thể hoán đổi mô hình mà không cần thay đổi mã máy khách của mình. Chỉ cần cập nhật ID mô hình trong cấu hình của bạn. Đảm bảo máy khách của bạn hỗ trợ lược đồ JSON mới nhất. Các phiên bản cũ hơn có thể từ chối các tham số mới. Kiểm tra kết nối của bạn trước khi triển khai sang sản xuất. Xác minh rằng định dạng phản hồi phù hợp với trình phân tích cú pháp của bạn.

Cấu hình Xác thực và Khóa

Bảo vệ khóa API của bạn trong các biến môi trường ngay sau khi tạo.

Tạo một khóa thông qua bảng điều khiển nhà cung cấp. Lưu nó ở vị trí bảo mật. Không bao giờ mã hóa cứng nó trong kho lưu trữ nguồn của bạn. Truyền nó qua Authorization: Bearer <key> header. Mỗi khóa được liên kết với một tài khoản cụ thể. Bạn có thể xoay khóa nếu bạn nghi ngờ bị rò rỉ. Một số nhà cung cấp cho phép nhiều khóa cho mỗi tài khoản. Điều này cho phép bạn tách lưu lượng truy cập phát triển và sản xuất. Theo dõi việc sử dụng theo khóa để phát hiện các bất thường. Thu hồi các khóa không sử dụng thường xuyên. Sử dụng các khóa có thời hạn ngắn cho các tập lệnh tạm thời. Điều này giảm thiểu phạm vi ảnh hưởng của một cuộc xâm nhập. Đảm bảo phiên bản SDK của bạn hỗ trợ xác thực mã thông báo bearer. Các thư viện cũ có thể yêu cầu một định dạng header khác. Kiểm tra tài liệu cho SDK cụ thể của bạn. Xác minh rằng khóa có đủ số dư. Khóa hết hạn trả về lỗi 401. Khóa có số dư bằng không trả về lỗi 402. Phân biệt giữa hai trạng thái này trong logic của bạn.

Xử lý Luồng và Sử dụng Token

Bật streaming để giảm độ trễ và phản hồi người dùng theo thời gian thực.

Đặt stream: true trong phần tải trọng yêu cầu. Máy chủ gửi một chuỗi các Server-Sent Events (SSE). Mỗi sự kiện chứa một chunk văn bản từng phần. Bạn phải ghép các chunk này lại để tạo thành phản hồi đầy đủ. Chunk cuối cùng thường bao gồm thống kê sử dụng token. Điều này cho phép bạn theo dõi chi phí theo thời gian thực. Không có streaming, bạn phải chờ toàn bộ phản hồi. Điều này làm tăng đáng kể độ trễ cảm nhận. Streaming rất quan trọng cho các giao diện trò chuyện. Nó tạo ra hiệu ứng gõ chữ mang lại cảm giác phản hồi nhanh. Hãy cẩn thận với xử lý lỗi trong quá trình streaming. Nếu kết nối bị ngắt, bạn sẽ mất chunk hiện tại. Logic kết nối lại nên bảo toàn trạng thái cuộc trò chuyện. Một số SDK xử lý streaming tự động. Số khác yêu cầu trình lắng nghe sự kiện thủ công. Hãy chọn cách tiếp cận phù hợp với kiến trúc của bạn. Đảm bảo trình phân tích cú pháp của bạn xử lý các chunk JSON không đầy đủ. Đừng giả định mỗi sự kiện là một đối tượng hoàn chỉnh. Đệm dữ liệu cho đến khi bạn có một cấu trúc hợp lệ.

Theo dõi Giới hạn Tốc độ và Độ đồng thời

Theo dõi số lượng yêu cầu mỗi phút để tránh gián đoạn dịch vụ.

OpenRouter áp dụng giới hạn tốc độ nghiêm ngặt cho mỗi khóa API. Vượt quá giới hạn này sẽ kích hoạt lỗi 429 Too Many Requests. Bạn phải triển khai cơ chế backoff theo cấp số nhân trong logic thử lại. Các yêu cầu đồng thời cũng tính vào giới hạn của bạn. Kiểm tra các tiêu đề phản hồi để biết hạn ngạch còn lại. Một số nhà cung cấp hiển thị các tiêu đề này trực tiếp. Những nhà cung cấp khác yêu cầu bạn suy luận giới hạn từ các lỗi. Độ đồng thời cao có thể làm cạn kiệt bộ kết nối của bạn. Đảm bảo máy khách của bạn quản lý kết nối một cách hiệu quả. Sử dụng bộ kết nối để giảm tải. Giám sát độ sâu hàng đợi của bạn trong các giờ cao điểm. Nếu bạn đạt giới hạn, hãy đợi trước khi thử lại. Randomize thời gian chờ của bạn để tránh vấn đề đàn bò tấn công. Ghi lại tất cả các sự cố giới hạn tốc độ để gỡ lỗi. Điều này giúp xác định các mẫu trong việc sử dụng của bạn. Điều chỉnh cài đặt độ đồng thời dựa trên các nhật ký này. Đừng giả định một khóa duy nhất có thể xử lý lưu lượng không giới hạn. Phân phối tải qua nhiều khóa nếu cần. Điều này đòi hỏi quản lý trạng thái cẩn thận. Đảm bảo mỗi khóa duy trì ngữ cảnh của riêng nó nếu cần.

Quản lý Thanh toán và Nạp Tiền bằng Tiền điện tử

Sử dụng tín dụng trả trước để chi trả cho việc sử dụng token mà không có phí hàng tháng.

Nạp tiền vào tài khoản bằng tiền điện tử. Các mạng được hỗ trợ bao gồm USDT trên TRC20 và USDC trên Base. Nạp tối thiểu bắt đầu từ $20. Tiền thưởng áp dụng cho các số tiền lớn hơn. Bạn nhận được thêm 5% cho $50, 10% cho $100 và 15% cho $200. Tín dụng không bao giờ hết hạn. Điều này rất lý tưởng cho các dự án dài hạn. Bạn chỉ trả tiền cho các token thực tế đã sử dụng. Lỗi và từ chối đều miễn phí. Điều này bảo vệ ngân sách của bạn khỏi các chi phí không mong đợi. Tài khoản mới nhận được $0.50 để thử nghiệm. Hoàn tiền không được cấp cho các giao dịch mua tiêu chuẩn. Các khoản tính sai được sửa chữa thông qua hỗ trợ. Đảm bảo ví của bạn hỗ trợ các mạng được yêu cầu. Xác minh địa chỉ hợp đồng trước khi gửi. Mạng sai có thể dẫn đến mất vốn. Kiểm tra số dư của bạn thường xuyên. Số dư thấp có thể làm gián đoạn dịch vụ một cách bất ngờ. Tự động hóa việc nạp tiền nếu có thể. Điều này đảm bảo khả năng sẵn có liên tục cho các nhiệm vụ quan trọng.

Kiểm tra bộ lọc nội dung và từ chối

Xác minh rằng mô hình hoạt động như mong đợi với các prompt không kiểm duyệt.

Các mô hình không kiểm duyệt vẫn có thể áp dụng các giới hạn cứng. Kiểm tra các hạn chế đối với các loại nội dung cụ thể. Kiểm tra với các cụm từ kích hoạt đã biết. Đảm bảo mô hình phản hồi phù hợp. Một số nhà cung cấp giữ lại các bộ lọc vì lý do pháp lý. Xác minh những điều này trước khi dựa vào mô hình cho dữ liệu nhạy cảm. Kiểm tra các trường hợp cạnh trong lĩnh vực của bạn. Gửi các lời nhắc thường kích hoạt từ chối. Quan sát định dạng phản hồi. Nó có trả về lý do từ chối không? Hay nó tạo nội dung im lặng? Ghi lại các hành vi này trong các bài kiểm tra tích hợp của bạn. Điều này ngăn ngừa những bất ngờ trong sản xuất. Nếu mô hình thay đổi hành vi của nó, hãy cập nhật các bài kiểm tra của bạn. Thông báo cho nhóm của bạn về bất kỳ sự thay đổi đáng kể nào. Sự nhất quán là chìa khóa cho niềm tin của người dùng. Đảm bảo ứng dụng của bạn xử lý từ chối một cách duyên dáng. Không giả sử mọi phản hồi đều hợp lệ. Xác định cấu trúc đầu ra. Kiểm tra các lỗi hallucination hoặc định dạng. Điều này đảm bảo trải nghiệm người dùng đáng tin cậy.

Triển khai Xử lý Lỗi cho Các Yêu cầu Miễn phí

Xử lý lỗi một cách tinh tế để duy trì trải nghiệm người dùng mượt mà.

Lỗi mạng, thời gian chờ và lỗi máy chủ có thể xảy ra. Hãy triển khai logic thử lại với độ trễ tăng dần. Phân biệt giữa lỗi tạm thời và lỗi vĩnh viễn. Lỗi 429 là lỗi tạm thời. Hãy đợi và thử lại. Lỗi 400 là lỗi vĩnh viễn. Hãy kiểm tra dữ liệu đầu vào của bạn. Lỗi 500 là lỗi phía máy chủ. Hãy thử lại một cách thận trọng. Hãy ghi log tất cả các lỗi để gỡ lỗi. Bao gồm tải trọng yêu cầu và thân phản hồi. Điều này giúp tái hiện sự cố nhanh chóng. Không hiển thị lỗi thô cho người dùng. Hãy định dạng chúng thành các thông báo thân thiện với người dùng. Hãy xử lý cẩn thận các lỗi streaming. Ngắt kết nối với luồng sự kiện. Dọn dẹp tài nguyên. Đảm bảo ứng dụng của bạn không bị rò rỉ bộ nhớ. Kiểm tra kỹ các kịch bản lỗi. Mô phỏng việc mất kết nối mạng. Mô phỏng thời gian chờ của máy chủ. Xác minh rằng logic khôi phục của bạn hoạt động. Điều này đảm bảo độ tin cậy trong các điều kiện bất lợi.

Mở rộng với JSON Mode và Tool Calling

Sử dụng đầu ra có cấu trúc để trích xuất dữ liệu và thực thi hàm đáng tin cậy.

Bật chế độ JSON bằng cách đặt response_format: {type: "json_object"}. Điều này buộc mô hình xuất ra JSON hợp lệ. Sử dụng điều này để phân tích cú pháp dữ liệu hoặc tạo cấu hình. Gọi công cụ cho phép mô hình thực thi các hàm. Xác định các công cụ của bạn trong tải trọng yêu cầu. Mô hình quyết định khi nào gọi chúng. Truyền kết quả lại cho mô hình. Nó có thể tạo phản hồi cuối cùng dựa trên đầu ra. Điều này tạo ra một vòng lặp cho các nhiệm vụ phức tạp. Đảm bảo các định nghĩa công cụ của bạn rõ ràng. Các công cụ mơ hồ dẫn đến các lệnh gọi không chính xác. Xác thực đầu ra JSON trước khi phân tích cú pháp. Điều này ngăn chặn lỗi thời gian chạy trong mã của bạn. Sử dụng gọi công cụ cho các nhiệm vụ trích xuất dữ liệu. Nó cải thiện độ chính xác đáng kể. Kiểm tra với nhiều định dạng đầu vào khác nhau. Đảm bảo mô hình xử lý các trường hợp biên. Tài liệu về các công cụ có sẵn cho nhóm của bạn. Điều này đảm bảo việc sử dụng nhất quán trên các dự án.

Xem lại Chính sách Quyền riêng tư và Sử dụng Dữ liệu

Hiểu cách nhà cung cấp lưu trữ và sử dụng dữ liệu của bạn.

Kiểm tra chính sách quyền riêng tư để xem chi tiết về việc lưu giữ dữ liệu. Một số nhà cung cấp sử dụng dữ liệu của bạn để huấn luyện mô hình. Số khác giữ dữ liệu ở chế độ riêng tư. Đảm bảo dữ liệu của bạn không được sử dụng để cải thiện mô hình nếu điều đó quan trọng đối với bạn. Xác minh các tiêu chuẩn mã hóa. Dữ liệu phải được mã hóa khi truyền tải và khi lưu trữ. Kiểm tra xem nhật ký (logs) có được lưu trữ không. Nhật ký có thể chứa các lệnh prompt của bạn. Đảm bảo các nhật ký này được bảo mật. Xem lại điều khoản dịch vụ để tìm các điều khoản về trách nhiệm pháp lý. Hiểu rõ ai là chủ sở hữu nội dung do mô hình tạo ra. Một số nhà cung cấp tuyên bố quyền đối với đầu ra của bạn. Đảm bảo điều này phù hợp với nhu cầu của bạn. Xóa tài khoản nếu bạn không còn sử dụng dịch vụ. Xác minh rằng dữ liệu của bạn đã được xóa. Liên hệ bộ phận hỗ trợ nếu bạn có thắc mắc. Ghi lại các cài đặt quyền riêng tư của bạn để phục vụ mục đích kiểm toán. Điều này đảm bảo tuân thủ các chính sách nội bộ.