Chuyển đến nội dung chính
Detector pii built-in bao quát các entity phổ biến — email, điện thoại, thẻ tín dụng, SSN, IBAN, JWT, cloud key. Nhưng dữ liệu nhạy cảm của bạn là của bạn: ID nhân viên, số case nội bộ, tham chiếu tài khoản khách hàng, định dạng đơn hàng của một đối tác. Một entity PII tùy chỉnh để bạn dạy cùng quy tắc masking nhận diện các hình dạng đó, nên gateway redact chúng trước khi mô hình — hoặc bất kỳ tool downstream nào — từng thấy chúng. Trang này bao quát một điều mà entity tùy chỉnh thêm vào quy tắc PII detection: các detector của riêng bạn. Về engine đầy đủ — mọi loại quy tắc, giai đoạn, và route — xem tài liệu tham khảo Guardrails.
Mọi bước ở đây là một hành động console trên gateway được lưu trữ (api.orcarouter.ai). Bạn soạn guardrail dưới phiên của riêng bạn; chỉ cuộc gọi /v1/* cuối cùng dùng một relay key sk-orca-.... Tạo và chỉnh sửa guardrails yêu cầu Developer+ trong workspace.

​
1. Khi nào bạn cần một guardrail detector PII LLM tùy chỉnh

Bộ entity built-in là đóng và được chia sẻ trên engine, validator, và trình tạo quy tắc. Nó là công cụ đúng cho các định danh chuẩn. Dùng tới một entity tùy chỉnh khi dữ liệu bạn muốn redact có một hình dạng dự đoán được mà không built-in nào bao quát:

Định danh nội bộ

ID nhân viên (EMP482915), số case, tham chiếu ticket, SKU nội bộ — bất cứ thứ gì có tiền tố cố định và chuỗi chữ số.

Số tài khoản & đơn hàng

Tham chiếu tài khoản khách hàng hoặc định dạng đơn hàng của một đối tác không bao giờ nên đến một mô hình bên thứ ba nguyên văn.

Số có checksum

Số kiểu thẻ hoặc số thành viên qua được kiểm tra Luhn — thêm checksum để cắt dương tính giả trên các chuỗi chữ số trông giống.

Mã đặc thù theo lĩnh vực

Số hợp đồng, ID khiếu nại, serial thiết bị — bất kỳ token nào ngành của bạn coi là nhạy cảm nhưng detector chung không biết.
Một entity tùy chỉnh xếp lớp trên bộ built-in bên trong một quy tắc pii. Nó phát hiện match và áp dụng hành động của quy tắc — mask, block, hoặc flag — chính xác như một entity built-in làm.

​
2. Giải phẫu một entity tùy chỉnh

Một entity tùy chỉnh là ba trường nhỏ cộng một thẻ mask tùy chọn. Bạn thêm chúng trong editor quy tắc pii dưới Custom entities:
TrườngBắt buộcNó làm gì
namecóID ổn định, ví dụ employee_id. ASCII viết thường / chữ số / _, phải bắt đầu bằng một chữ cái. Chảy vào Matches feed và audit log.
patterncóMột regex Go RE2 (thời gian tuyến tính, không backreference). Phải biên dịch được.
checksumkhôngluhn xác thực mỗi match với thuật toán Luhn. Chỉ "" (none) hoặc "luhn" được chấp nhận.
mask_withkhôngThay thế nguyên văn trên một hành động mask. Mặc định là [<UPPERCASE_NAME>].
name tuân theo cùng quy ước key như phần còn lại của gateway — viết thường, bắt đầu bằng một chữ cái, không khoảng trắng hay gạch nối. Chọn một cái rõ ràng (case_number, partner_order_id); đó là cái bạn sẽ thấy trong Matches feed khi quy tắc kích hoạt.

​
Checksum Luhn tùy chọn

Nhiều định danh “kiểu số” — thẻ thanh toán, một số số thành viên và tài khoản — mang một chữ số kiểm tra Luhn (mod-10). Một regex trần như \d{16} match bất kỳ chuỗi 16 chữ số nào, bao gồm số điện thoại, dấu thời gian, và tổng đơn hàng. Đặt checksum: "luhn" làm detector kích hoạt chỉ khi các chữ số đã match cũng qua được kiểm tra Luhn, nên các chuỗi trông giống lọt qua sạch sẽ và tỷ lệ dương tính giả của bạn giữ thấp. Để trống nó cho các token không checksum như một ID nhân viên.

​
Thẻ mask của riêng bạn

Trên một hành động mask, một email built-in render thành [EMAIL]. Một entity tùy chỉnh render thành [<UPPERCASE_NAME>] theo mặc định — một match employee_id trở thành [EMPLOYEE_ID]. Đặt mask_with để ghi đè điều đó nguyên văn (ví dụ <id> hoặc ***) khi bạn muốn một token thay thế cụ thể trong văn bản mô hình nhận. Xem Định dạng masking cho các quy tắc render trên các loại entity.

​
3. Một ví dụ cụ thể

Giả sử prompt của bạn mang ID nhân viên dạng EMP theo sau bởi sáu chữ số, và bạn muốn chúng được che ở giai đoạn input để mô hình thượng nguồn không bao giờ thấy một ID thực. Thêm một entity tùy chỉnh duy nhất vào một quy tắc pii: 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email"],
  "custom_entities": [
    {
      "name": "employee_id",
      "pattern": "EMP\\d{6}",
      "mask_with": "[EMPLOYEE_ID]"
    }
  ]
}
Quy tắc đó che cả email chuẩn và ID nhân viên của bạn trong cùng một lượt. Test nó trong tab Test trước khi gắn một key: 
Forward EMP482915's note to jane@acme.com

Forward [EMPLOYEE_ID]'s note to [EMAIL]
Không có gì được gửi lên thượng nguồn và không có gì được đo. Sau đó gắn guardrail vào một key (xem Gắn vào một key) và gọi /v1/chat/completions y như trước — gateway che request trước khi chuyển tiếp, không đổi SDK.
Masking chạy ở cả hai giai đoạn: một quy tắc input redact request trước khi mô hình thấy nó, và một quy tắc output redact phản hồi của mô hình — bao gồm phản hồi streaming, nơi scanner viết lại match trong luồng. Hành động block cũng được thực thi ở cả hai giai đoạn. Để gate phản hồi mô hình, xem quy tắc giai đoạn output.

​
Một ví dụ có checksum

Cho một số thành viên kiểu thẻ, thêm kiểm tra Luhn để các chuỗi 16 chữ số không phải số hợp lệ không match: 
{
  "name": "member_card",
  "pattern": "\\d{16}",
  "checksum": "luhn",
  "mask_with": "[MEMBER_CARD]"
}

​
4. Giới hạn và xác thực

Trình tạo quy tắc xác thực mọi entity tùy chỉnh khi lưu — một detector tồi không bao giờ đến được đường nóng.
Mỗi entity tùy chỉnh là một lần quét regex trên toàn bộ văn bản, nên giới hạn theo từng quy tắc là 25. Giới hạn giữ đường nóng tuyến tính; các pattern đã biên dịch được cache giữa các request. Cần nhiều hình dạng hơn? Tách chúng qua nhiều quy tắc pii trong cùng một guardrail.
pattern là một regex Go RE2 — thời gian tuyến tính, không backreference. Validator từ chối một pattern không biên dịch được, với entity vi phạm được nêu tên trong lỗi.
Chỉ "" (không kiểm tra) và "luhn" được chấp nhận. Bất cứ thứ gì khác — "sha256", "mod10", kể cả "LUHN" — bị từ chối khi lưu.
Một name phải bắt đầu bằng một chữ cái và chỉ dùng ASCII viết thường, chữ số, và gạch dưới. Hai entity tùy chỉnh trong một quy tắc không thể chia sẻ một tên.

​
5. Ghi đè hành động theo từng entity

Một entity tùy chỉnh tham gia vào cùng map entity_actions như một entity built-in. Một quy tắc pii có thể che hầu hết mọi thứ nhưng block trên một detector tùy chỉnh độ nhạy cao — tham chiếu entity bằng name của nó: 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "phone"],
  "custom_entities": [
    { "name": "ssn_internal", "pattern": "ID-\\d{9}", "checksum": "luhn" }
  ],
  "entity_actions": {
    "ssn_internal": "block"
  }
}
Các key trong entity_actions phải tham chiếu một entity built-in được bật trên quy tắc hoặc name của một entity tùy chỉnh; các giá trị phải là block, mask, flag, hoặc annotate. Validator từ chối mọi thứ khác.

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

PII Shield

Quy tắc masking duy nhất mà entity tùy chỉnh xếp lớp lên — bộ detector built-in và các thẻ mask có kiểu.

Định dạng masking

Cách mỗi entity render trên một hành động mask, và cách mask_with ghi đè nó.

Regex detector

Khi nào một quy tắc regex thuần phù hợp hơn một entity PII có kiểu.

Tinh chỉnh dương tính giả

Dùng Matches feed và checksum để chỉnh độ chính xác.
Đọc tài liệu tham khảo Guardrails cho quy tắc PII hoàn chỉnh — mọi trường, eval harness, và API đầy đủ — hoặc Tạo guardrail đầu tiên của bạn để đi qua vòng lặp đầu-cuối từ đầu.