Hướng dẫn OpenRouter: Cách quản lý cấu hình chuyên nghiệp với Presets

Bạn đã đặt cùng một tên model, system prompt và temperature trong một ứng dụng web, một batch script và một notebook. Bây giờ, nếu muốn thay đổi temperature hoặc model, bạn phải chỉnh sửa cả ba nơi.

Chúng tôi xây dựng các preset để giải quyết chính xác vấn đề này. Một preset là cấu hình-dưới-dạng-mã (config-as-code) cho các lệnh gọi LLM của bạn, bao gồm một tập hợp các model, system prompt, định tuyến nhà cung cấp (provider routing) và các tham số lấy mẫu (sampling parameters) được đặt tên và đánh phiên bản. Chúng tôi cho phép bạn định nghĩa nó một lần và sử dụng tên của nó ở mọi nơi. Khi bạn thay đổi preset, mọi ứng dụng sử dụng nó đều sẽ cập nhật theo.

Hướng dẫn này bổ sung cho tài liệu tham khảo về preset và thông báo ra mắt. Bạn sẽ tạo một preset, sử dụng nó trong một API call và thực hiện hai thiết lập: một preset tăng cường prompt hình ảnh và một cấu hình Fusion cố định.

Tóm tắt (Tl;dr)

OpenRouter preset là gì?

OpenRouter preset là một cấu hình được đặt tên và đánh phiên bản, lưu trữ các lựa chọn model, system prompt, tùy chọn định tuyến nhà cung cấp và các tham số lấy mẫu của bạn. Chúng tôi cho phép bạn sử dụng nó trong bất kỳ yêu cầu API nào thông qua slug của nó. Điều này giúp tách biệt thiết lập LLM ra khỏi mã nguồn ứng dụng của bạn.

Hãy coi preset giống như một tệp.env hoặc một module Terraform, nơi cấu hình nằm ngoài logic ứng dụng và được tham chiếu bằng tên thay vì sao chép trực tiếp vào mã nguồn. Điểm khác biệt nằm ở nơi lưu trữ và quyền thay đổi. Tệp.env vẫn đi kèm với repo của bạn và cần triển khai lại (redeploy) để cập nhật. Thay vào đó, chúng tôi lưu trữ preset trên bảng điều khiển OpenRouter, vì vậy việc thay đổi nó sẽ cập nhật ngay lập tức mọi ứng dụng đang tham chiếu đến nó.

Một preset đơn lẻ có thể chứa:

Preset so với việc hardcode body yêu cầu của bạn

Cách tạo preset đầu tiên của bạn

Bước 1: Mở trình chỉnh sửa preset

Truy cập openrouter.ai/settings/presets và tạo một preset. Hãy chọn một slug mà bạn dễ nhớ, vì bạn sẽ sử dụng nó dưới dạng @preset/slug-của-bạn.

Bước 2: Chọn model và định tuyến

Chọn một model hoặc thêm một danh sách ưu tiên. Nếu model đầu tiên thất bại do giới hạn tốc độ (rate limit), sự cố hoặc quá tải ngữ cảnh, chúng tôi sẽ thử model tiếp theo. Bạn thiết lập thứ tự dự phòng (fallback order) một lần trong preset thay vì lặp lại trong mỗi yêu cầu.

Thiết lập định tuyến nhà cung cấp tại đây, như trong ảnh chụp màn hình phía trên. Bạn có thể sắp xếp theo giá hoặc độ trễ, hoặc chặn một nhà cung cấp khỏi các yêu cầu của bạn.

Bước 3: Thêm system prompt và cài đặt lấy mẫu

Thêm system prompt và thiết lập temperature, top_p cùng các tham số lấy mẫu khác. Những cài đặt này sẽ trở thành mặc định cho mọi yêu cầu sử dụng preset đó.

Bước 4: Tham chiếu nó từ một API call

Đặt trường model thành preset của bạn. Hãy so sánh các yêu cầu này.

Trước đây, với mọi tham số trong yêu cầu:

Sau đó, với một tham chiếu preset:

Bạn cũng có thể tạo preset thông qua API bằng yêu cầu POST tới endpoint preset. Chúng tôi lưu các trường thuộc về cấu hình preset và bỏ qua các trường tạm thời như messages, stream và prompt.

Bạn có thể ghi đè cài đặt preset trong mỗi yêu cầu. Nếu body yêu cầu bao gồm temperature, giá trị đó sẽ ưu tiên hơn giá trị trong preset. Đây là kiểu hợp nhất nông (shallow merge), vì vậy các trường trong yêu cầu sẽ thay thế các trường tương ứng trong preset, và chúng tôi giữ lại bất kỳ trường preset nào bạn không đề cập đến. Ngoại lệ là tools: chúng tôi kết hợp các công cụ của preset với các công cụ của yêu cầu, và một công cụ trong yêu cầu sẽ thay thế công cụ cùng tên trong preset. Bạn cũng có thể sử dụng trường preset riêng ("preset": "@preset/tech-writer") hoặc dạng kết hợp ("model": "anthropic/claude-opus-4.8@preset/tech-writer"). Trường preset cần có tiền tố @preset/ đầy đủ. Một slug không có tiền tố sẽ bị bỏ qua.

Bạn có thể đặt một preset mặc định không?

Không áp dụng cho API. Các preset có phiên bản. Việc lưu một slug hiện có sẽ tạo ra một phiên bản mới và kích hoạt nó, nhưng không có preset mặc định toàn cục cho API. Mọi yêu cầu đều phải chỉ định tên preset. Chatroom có cài đặt Default Preset trong mục Settings > Preferences áp dụng cho các tin nhắn chat mới.

Đối với API, hãy đưa hành vi mặc định của bạn vào một preset và sử dụng preset đó ở mọi nơi. Nếu bạn muốn câu trả lời ngắn gọn, hãy thêm quy tắc đó vào system prompt của preset (“Trả lời trong ba câu hoặc ít hơn trừ khi được yêu cầu mở rộng.”) và thiết lập các tham số lấy mẫu. Mọi dịch vụ sử dụng @preset/short-answers sẽ tuân theo các mặc định đó trừ khi một yêu cầu ghi đè chúng.

Sử dụng preset theo tên mang lại cho bạn hành vi ổn định mà bạn có thể thay đổi tại một nơi duy nhất. Mô hình tương tự mở rộng cho các thiết lập phức tạp hơn. Dưới đây là hai ví dụ thực tế.

Trường hợp sử dụng 1: Preset tăng cường prompt hình ảnh

Các model hình ảnh thường hoạt động tốt hơn với các prompt chi tiết. Thay vì thêm chi tiết đó bằng tay mỗi lần, hãy kết hợp một model văn bản với công cụ tạo hình ảnh trong một preset. Model văn bản sẽ tinh chỉnh từng prompt trước khi nó được gửi đến model hình ảnh.

Preset lưu trữ một model văn bản, một system prompt giúp biến yêu cầu ngắn thành một bản tóm tắt hình ảnh đầy đủ bao gồm chủ thể, bố cục, ánh sáng, bảng màu và phong cách, cùng với công cụ tạo hình ảnh.

Sau khi preset được lưu, hãy kiểm tra trực tiếp trong Chatroom bằng cách mở preset và chọn “Test in Chat.” Gửi một prompt ngắn như “một góc đọc sách ấm cúng bên cửa sổ đầy mưa,” và preset sẽ áp dụng system prompt cùng công cụ hình ảnh của nó. Model văn bản sẽ mở rộng prompt ngắn của bạn thành một bản tóm tắt hình ảnh đầy đủ, sau đó tự động gọi công cụ hình ảnh. Đây là kết quả hiển thị.

Preset lưu trữ mảng tools và tool_choice cùng với model, system prompt và các tham số lấy mẫu.

Mọi ứng dụng sử dụng @preset/image-enhancer đều nhận được hành vi tương tự. Sách hướng dẫn (cookbook) về preset-enhanced images sẽ hướng dẫn chi tiết toàn bộ quy trình.

Trường hợp sử dụng 2: Ghim cấu hình Fusion dưới dạng preset

Thiết lập Fusion chạy một nhóm (panel) các model song song với model chính của bạn, và model chính sẽ viết câu trả lời cuối cùng dựa trên kết quả đầu ra của nhóm đó. Hãy lưu trữ toàn bộ thiết lập này trong một preset, sau đó sử dụng nó thông qua một tham chiếu duy nhất.

Lưu trữ công cụ openrouter:fusion, cùng với nhóm analysis_models và model phân tích (analyst model) của nó vào trong tools của preset, sau đó gọi @preset/fusion-panel từ bất kỳ đâu. Ứng dụng web, công cụ đánh giá và Slack bot của bạn đều sử dụng cùng một nhóm đó. Bạn điều chỉnh nó trong bảng điều khiển thay vì phải chỉnh sửa ba cơ sở mã nguồn. Để biết các trường chính xác mà cấu hình Fusion sử dụng và cách nhóm hoạt động, hãy xem tài liệu về Fusion.

Điều này cũng cung cấp cho các kỹ sư ML một cấu hình đánh giá có thể lặp lại với cùng các model, cài đặt lấy mẫu và định tuyến dưới một slug ổn định.

Quản lý preset theo thời gian

Mỗi khi bạn lưu một preset với một slug đã tồn tại, hệ thống của chúng tôi sẽ tạo một phiên bản mới và kích hoạt nó. Các yêu cầu API sử dụng preset đó sẽ nhận được phiên bản đang hoạt động.