Chuyển đến nội dung chính
Bạn đã có một guardrail đã lưu và bạn muốn một API key cụ thể được sàng lọc bởi nó — không phải toàn bộ workspace. Đó chính là mục đích của liên kết guardrail theo từng API key: đặt guardrail_id trên key và mọi cuộc gọi /v1/* được thực hiện với key đó sẽ được sàng lọc ở request kế tiếp, mà không cần triển khai lại và không đổi SDK. Trang này chỉ đề cập đến liên kết — cách gắn, cách phân giải chọn chính sách hiệu lực, và công tắc off làm gì. Để xem các loại quy tắc, hành động, và giai đoạn, xem Tham chiếu Guardrails.

​
1. Liên kết một guardrail theo từng API key với guardrail_id

Một guardrail có phạm vi workspace, nhưng việc thực thi được quyết định theo từng key. Mỗi API key mang một trường guardrail_id. Trỏ nó đến một guardrail và key đó — và chỉ key đó — được sàng lọc bởi chính sách đó. Điều này cho phép một workspace chạy các chính sách khác nhau trên các key khác nhau:
  • một key production liên kết với một pii-blocker nghiêm ngặt,
  • một key staging liên kết với một chính sách flag-only nhẹ hơn,
  • một key internal không gắn gì.
Liên kết nằm trên key trong gateway, nên chỉnh sửa guardrail dịch chuyển key đã liên kết ở request kế tiếp của nó. Ứng dụng của bạn vẫn gọi https://api.orcarouter.ai/v1/chat/completions y như trước.
Relay key (sk-orca-…) là cái mà ứng dụng của bạn gửi. Gắn một guardrail vào nó là một hành động console / token-API được xác thực bằng phiên của bạn — bạn không bao giờ cấu hình một guardrail bằng chính relay key.

​
2. Gắn nó trong console

Cấu hình liên kết từ console (kiểm soát theo vai trò: chỉnh sửa key và guardrails yêu cầu Developer+).
1

Mở key

Vào /console/token và tạo hoặc chỉnh sửa API key bạn muốn được sàng lọc.
2

Chọn guardrail

Trong key editor, chọn guardrail của bạn từ dropdown Guardrail. Cái này đặt guardrail_id trên key.
3

Lưu

Liên kết có hiệu lực ở request kế tiếp của key đó. Không triển khai lại.
Sau đó, một cuộc gọi relay bình thường với key đã liên kết được sàng lọc tự động: 
curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Reply to jane@acme.com please"}
    ]
  }'
Nếu guardrail đã liên kết che email ở giai đoạn input, mô hình thượng nguồn thấy [EMAIL] và không bao giờ thấy địa chỉ — cùng cuộc gọi, không đổi client.
Để sàng lọc mọi key trong workspace thay vì một, hãy đặt guardrail làm mặc định workspace thay vì liên kết từng key. Xem Guardrail mặc định tài khoản.

​
3. Cách phân giải chọn guardrail hiệu lực

Trên mỗi request, gateway phân giải chính xác một guardrail hiệu lực (hoặc không có) theo thứ tự này:
Nếu guardrail_id của key trỏ đến một guardrail và guardrail đó tồn tại và được bật, nó áp dụng. Một liên kết tường minh có thẩm quyền — nó không bao giờ âm thầm fallback về mặc định workspace.
Nếu key không có liên kết (guardrail_id là 0 / chưa đặt), guardrail mặc định đã bật của workspace sẽ áp dụng, nếu có một cái được đặt.
Không thực thi. Request giống hệt từng byte với một workspace chưa bao giờ bật tính năng này — không có gì bị block, masked, hoặc ghi log.
Quyết định là một lần tra cứu có chỉ mục trên đường nóng và là fail-open: nếu phân giải gặp một lỗi thoáng qua, gateway suy giảm về không thực thi thay vì làm hỏng request. An toàn suy giảm; tính sẵn sàng được bảo toàn.

​
4. Công tắc off: tắt một liên kết, không fallback

Đây là phần mọi người bỏ sót. Một liên kết key tường minh là thẩm quyền riêng của nó — nên tắt guardrail đã gắn sẽ tắt việc thực thi cho key đó, và nó không fallback về mặc định workspace.
Trạng thái keyCái gì sàng lọc request
guardrail_id → guardrail đã bậtguardrail đó
guardrail_id → guardrail bị tắtkhông có gì (không fallback)
guardrail_id → đã xóa / thiếukhông có gì (không fallback)
guardrail_id = 0 / chưa đặtmặc định workspace, nếu có
Tắt một guardrail đã gắn là công tắc off cho key đó, không phải hạ cấp về mặc định. Nếu bạn muốn một key fallback về mặc định workspace, hãy xóa liên kết của nó (đặt guardrail_id thành 0) — đừng chỉ tắt guardrail mà nó trỏ tới.
Đây là một khác biệt có chủ ý so với firewall: một key với một chính sách firewall đã gắn bị tắt vẫn fallback về chính sách firewall mặc định workspace, trong khi một guardrail đã gắn bị tắt sẽ phân giải về không có gì. Cùng ý tưởng, fallback ngược lại — xem Guardrails vs. firewall.

​
5. Gỡ hoặc xóa liên kết

Để ngừng sàng lọc một key với một guardrail cụ thể, bạn có hai động tác riêng biệt với kết quả khác nhau:
  • Xóa liên kết — đặt guardrail_id của key thành 0. Key giờ phân giải về mặc định workspace (nếu có một cái tồn tại), hoặc về không có gì.
  • Tắt guardrail — chuyển enabled của guardrail thành off. Mọi key được gắn tường minh với nó giờ phân giải về không có gì (theo §4), trong khi các key dựa vào nó làm mặc định workspace rớt xuống không thực thi.
Chọn xóa khi bạn muốn key ở trên baseline workspace; chọn tắt khi bạn muốn tạm dừng chính sách đó ở mọi nơi nó là liên kết có tên.

​
6. Một request được sàng lọc tốn (và không tốn) gì

Một khi một guardrail phân giải, các quy tắc của nó quyết định request. Hai kết quả đáng biết cho một key đã liên kết:
  • Một block trả về HTTP 400 với mã lỗi guardrail_blocked, nêu tên guardrail và quy tắc đã kích hoạt. Nó tốn không quota — một block ở giai đoạn input kích hoạt trước khi đo lường, một block ở giai đoạn output hoàn trả lại quota đã tiêu trước — và nó được đánh dấu skip-retry.
  • Một mask viết lại match thành một tag có kiểu (vd: [EMAIL]) và cho request đi qua đã làm sạch; mô hình thượng nguồn không bao giờ thấy bản gốc.
Xem trang lỗi guardrail_blocked để biết hình dạng phản hồi chính xác, và Streaming coverage để biết cách các quy tắc output hành xử trên các phản hồi đã stream.

​
7. Đi đâu tiếp theo

Tạo guardrail đầu tiên của bạn

Xây dựng chính sách bạn sẽ liên kết với một key.

Guardrail mặc định tài khoản

Sàng lọc mọi key trong workspace cùng lúc.

Tham chiếu Guardrails

Loại quy tắc, hành động, giai đoạn, PII, judge, grounding.

Key, chính sách & workspace

Cách các liên kết được phân phạm vi trên gateway.