Bỏ qua để đến nội dung
AggregaAggrega
Chọn ngôn ngữ: Tiếng Việt
Trang này được dịch bằng máy. Đọc bản gốc tiếng Anh.

Một AI gateway giữ dữ liệu cá nhân ngoài nhật ký của nó

Một trợ lý hỗ trợ phải làm việc với tên và địa chỉ email của khách hàng, vì vậy mô hình mà nó gọi phải nhìn thấy chúng. Gateway đứng trước mô hình đó ghi nhật ký phục vụ kiểm toán và gỡ lỗi, và các nhật ký đó không được giữ lại chúng. Workspace này biên dịch một gateway như vậy thành các manifest Kubernetes.

Thứ thực hiện việc này là một giá trị của chính gateway, values.log_masking trên core/gateway/litellm. Nó che bản sao của mỗi lời gọi mà gateway chuyển cho nhật ký của mình, và không gì khác: mô hình nhận yêu cầu đúng như bên gọi đã gửi, và bên gọi nhận phản hồi đúng như mô hình đã viết. Đó là điểm khác biệt so với Feature core/data-masking, vốn ẩn văn bản khỏi chính mô hình. Hai cách này là lựa chọn thay thế cho nhau, và phần về cách chọn giữa chúng bên dưới cho thấy điều gì xảy ra khi cả hai được đặt trên cùng một gateway.

Workspace này không tự định nghĩa entity catalog nào. Ba tệp entity ở đây — một Aggregate, một Manifest và một Release — là toàn bộ những gì cần viết.

Những gì ví dụ này xây dựng

instanceComponent trong catalogvai trò ở đây
routercore/gateway/litellmAI gateway: một alias được công bố, assistant, được phục vụ từ model nối vào socket models của nó
gptcore/ai-model/openaimodel đứng sau alias đó, chính API của OpenAI, được truy cập dưới dạng tham chiếu: không có gì chạy cho nó trong cluster
analyzercore/security/presidio-analyzertìm các đoạn nhạy cảm trong một văn bản
anonymizercore/security/presidio-anonymizerthay thế các đoạn được giao cho nó

Ba cạnh uses: socket models của gateway tới model, mang theo làm credential của nó khóa mà gateway xuất trình cho model, cùng các socket pii_analyzer và pii_anonymizer của gateway tới hai dịch vụ nhận dạng. Aggregate gắn credential đó mà không nêu tên một secret, và Release nêu tên nó trong infra của phần gắn: một Secret mà namespace đã có sẵn, được realization của Manifest tham chiếu và không render. values.log_masking của gateway liệt kê những gì cần che: một biểu thức chính quy cho số ticket của công ty dưới patterns, và các loại thực thể PERSON và EMAIL_ADDRESS dưới entities. Không có danh sách mặc định; một gateway không liệt kê gì thì không che gì trong log, và render giống hệt như khi không có giá trị này.

Tạo ví dụ

Bạn có thể build ví dụ này bằng các lệnh bên dưới, hoặc để trợ lý AI của bạn build giúp bạn.

Ghi ví dụ vào một thư mục mới đặt theo tên của nó:

Terminal window
aggrega scaffold --example ai-gateway-log-masking

Sau đó nó in ra các lệnh cần chạy tiếp theo. Lệnh đầu tiên chuyển vào thư mục mới:

Terminal window
cd ai-gateway-log-masking

Build

Terminal window
aggrega build --release release.yaml --auto-pull

Một release cần có lockfile trước khi build, và lockfile được tạo ra chứ không được phân phối kèm, nên một bản clone mới sẽ không có. Hãy resolve một lockfile trước, hoặc để quá trình build tự điền vào:

Terminal window
aggrega pull --release release.yaml # resolve once, then build with no flag
aggrega build --release release.yaml --auto-pull # or resolve during the build

Workspace này resolve các thực thể trong catalog từ registry mặc định mà .aggrega-config.yaml chỉ định. Chính Recipe của gateway viết phần che log, nên quá trình build không chạy plugin nào ngoài những plugin mà compiler mang sẵn.

Bản build in ra như sau, với <workspace> đại diện cho thư mục của ví dụ này:

[… omitted: the resolution's summary, a notice that core/referenced-secret declares origin in both of its pillars, and a total build time, which differs per run]
Build completed: 9 files written to <workspace>/dist

Với trợ lý AI

Một trợ lý AI được thiết lập với các công cụ của Aggrega cũng có thể làm như vậy: hãy dán prompt này vào trợ lý.

Chỉ dùng các công cụ của Aggrega và không tự tạo thư mục nào. Nếu thư mục workspace chưa có thư mục `ai-gateway-log-masking`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `ai-gateway-log-masking` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `ai-gateway-log-masking` mới. Sau đó gọi công cụ `build` với `workspace_root` đặt thành `ai-gateway-log-masking`, `release` đặt thành `release.yaml`, `auto_pull` đặt thành true và `write` đặt thành true. Hãy cho tôi biết bản build đã ghi những tệp nào; chúng nằm trong `ai-gateway-log-masking/dist/`.

Cây thư mục được kết xuất

dist/helm/
├── analyzer-default-service.yaml
├── analyzer-deployment.yaml
├── anonymizer-default-service.yaml
├── anonymizer-deployment.yaml
├── gpt-service.yaml
├── router-default-service.yaml
├── router-deployment.yaml
└── router/
├── litellm-gateway-config/
│ └── configmap.yaml
└── request-guard/
└── request-guard.yaml

Giá trị này không mang theo tệp nào của riêng nó. Recipe của gateway ghi nó vào cấu hình của gateway, và thêm vào ConfigMap của gateway một module mà cấu hình đó nạp. Mô hình kết xuất một tệp, gpt-service.yaml, một Service ánh xạ một tên trong cluster tới máy chủ API của OpenAI, api.openai.com; khóa của nó không kết xuất tệp nào, vì Secret chứa khóa đó đã tồn tại.

Bảng định tuyến, phần đầu của thân cấu hình gateway, có một mục, được ghi từ những gì mô hình công bố — endpoint của nó, URL cơ sở của API OpenAI, và tên mô hình của nó — và nêu tên biến mà Recipe của gateway dùng để cung cấp khóa của kết nối:

model_list:
- model_name: "assistant"
litellm_params:
model: "openai/gpt-4o"
api_base: "https://api.openai.com/v1"
api_key: os.environ/LITELLM_MODEL_ASSISTANT_API_KEY

Mục guardrail

Đây là phần thân cấu hình của gateway, khóa config.yaml của dist/helm/router/litellm-gateway-config/configmap.yaml, từ phần litellm_settings trở đi:

[… omitted: the routing table]
litellm_settings:
callbacks:
- /etc/litellm-request-guard/request_field_filter.filter
- log_masking.withhold_failed_calls
redact_messages_in_exceptions: true
guardrails:
- guardrail_name: "router.log-masking"
litellm_params:
guardrail: log_masking.LogMasking
default_on: true
mode: logging_only
patterns:
- pattern_type: regex
name: "ticket"
pattern: "\\bTCK-[0-9]{6}\\b"
action: MASK
pii_entities_config:
"PERSON": MASK
"EMAIL_ADDRESS": MASK
general_settings:
disable_error_logs: true

Recipe của gateway viết toàn bộ phần này từ values.log_masking, và đặt tên mục theo gateway, ở đây là router, với một dấu chấm ở chỗ mà các mục guardrail do các hiện thực của thư viện chuẩn viết dùng dấu gạch nối, nên không attachment nào của chúng, dù tên là gì, có thể thế chỗ mục này. Có năm điều đáng đọc ra từ nó.

mode: logging_only là chế độ riêng của gateway cho một guardrail chạy ở chỗ một lệnh gọi đã hoàn tất được chuyển cho log của nó, và không ở đâu khác. Lớp mà mục này nạp tuân theo chế độ đó bất kể mục nêu tên gì, nên nó không bao giờ được gọi trên một yêu cầu trước khi yêu cầu được chuyển tiếp, hay trên một phản hồi trước khi phản hồi được trả về.

default_on: true chạy nó trên mọi lệnh gọi. Bên gọi không thể tắt nó từ yêu cầu, kể cả một yêu cầu đòi vô hiệu hóa các guardrail luôn bật của gateway.

Mẫu đến gateway đúng như khi được viết. Nó được so khớp bên trong gateway, không phân biệt chữ hoa chữ thường, và mọi kết quả khớp được thay thế vĩnh viễn bằng tên của mẫu viết hoa trong ngoặc vuông: [TICKET_REDACTED]. Gateway biên dịch biểu thức khi khởi động, và một biểu thức không biên dịch được sẽ khiến nó không khởi động được — compiler chuyển chuỗi đi qua mà không đọc nó.

Các loại thực thể được tìm bởi hai dịch vụ nhận dạng. Mục này không nêu địa chỉ nào: gateway đọc cả hai từ môi trường của nó, mà Recipe của gateway điền từ hai cạnh. Từ dist/helm/router-deployment.yaml, phần env của container của gateway:

env:
- name: LITELLM_MODEL_ASSISTANT_API_KEY
valueFrom:
secretKeyRef:
name: openai-api-key
key: api-key
- name: PRESIDIO_ANALYZER_API_BASE
value: http://analyzer-default:3000
- name: PRESIDIO_ANONYMIZER_API_BASE
value: http://anonymizer-default:3000

Biến đầu tiên là khóa của mô hình, được tham chiếu từ Secret mà Release nêu tên và không bao giờ được viết ra; hai biến còn lại là địa chỉ của các dịch vụ nhận dạng. Tên của một người trở thành <PERSON> và một địa chỉ thành <EMAIL_ADDRESS>.

Một lệnh gọi thất bại bị giữ lại thay vì bị che. Gateway không chạy guardrail ghi log nào cho một lệnh gọi thất bại, nên module mà mục này nạp cũng cung cấp log_masking.withhold_failed_calls, được đăng ký ngay sau guard của yêu cầu, và Recipe của gateway viết hai thiết lập bên cạnh nó. Callback nhận bản ghi của một lệnh gọi thất bại trước mọi callback được đăng ký sau nó, và thay mọi văn bản mà bên gọi hay mô hình viết bằng [TEXT_WITHHELD], dù có khớp hay không, và văn bản của lỗi bằng [ERROR_TEXT_WITHHELD], giữ nguyên những gì một lần thử lại gửi đi. disable_error_logs giữ các lệnh gọi thất bại khỏi spend logs, và redact_messages_in_exceptions giữ các thông điệp của yêu cầu khỏi chi tiết mà gateway đính kèm vào một lỗi.

Cùng ConfigMap đó mang một khóa thứ hai, log_masking.py: module mà guardrail của mục và mục callbacks thứ hai nêu tên. Recipe của gateway thêm module, mục callbacks đó, mục guardrail và hai thiết lập chỉ khi values.log_masking liệt kê một thứ gì đó, nên một gateway không liệt kê gì sẽ kết xuất ConfigMap không có thứ nào trong số đó, giống hệt từng byte như một gateway không có giá trị này.

Người đọc log thấy gì, và mô hình thấy gì

Lấy ví dụ một bên gọi có yêu cầu mang đoạn văn bản này:

My name is David Johnson and my email is david.johnson@example.com, ticket TCK-104882. Call me on 212-555-0147.

Khối ở trên và ba khối bên dưới minh họa những gì gateway đang chạy làm với nó; chúng không phải là đầu ra của bản build.

Nhà cung cấp mô hình nhận yêu cầu đúng như bên gọi đã gửi, và bên gọi nhận câu trả lời của mô hình đúng như khi nó đến. Một tích hợp ghi log mà gateway chuyển cuộc gọi đến sẽ nhận cùng các tin nhắn đó ở dạng đã che:

My name is <PERSON> and my email is <EMAIL_ADDRESS>, ticket [TICKET_REDACTED]. Call me on 212-555-0147.

Số điện thoại được ghi log đúng như khi gửi, vì phần đính kèm không liệt kê PHONE_NUMBER và không có mẫu nào khớp với nó. Văn bản không khớp với mục nào được liệt kê thì không bao giờ bị che.

Mọi bản sao của một cuộc gọi thành công mà gateway chuyển vào log của nó đều được che theo cùng một cách: các tin nhắn, các tin nhắn và câu trả lời trong payload ghi log tiêu chuẩn, một câu trả lời dạng stream khi gateway ghép nó lại, yêu cầu và câu trả lời như nhà cung cấp đã thấy, yêu cầu mà spend log lưu giữ, và câu trả lời mà mỗi tích hợp nhận được. Câu trả lời của mô hình cũng được che trong các bản sao đó:

Reply for <PERSON> (<EMAIL_ADDRESS>) about [TICKET_REDACTED].

Những gì không được che

Việc che log không giấu văn bản khỏi bất kỳ ai khác, và phần mô tả của values.log_masking nói rõ điều đó:

  • Nhà cung cấp mô hình nhận mọi thứ ở dạng không được che, và gateway cùng cả hai dịch vụ nhận dạng cũng vậy.
  • Một lời gọi thất bại không giữ văn bản yêu cầu nào trong bất kỳ log nào mà gateway ghi, và điều đó có hai cái giá. Dòng log riêng của gateway cho một lời gọi thất bại chỉ giữ loại lỗi, chẳng hạn An error was logged with its text withheld, as log masking is on: BadRequestError, nên thông báo của nhà cung cấp và traceback của nó không có trong log đó; và các lời gọi thất bại không có trong spend log và tổng chi tiêu hằng ngày, vốn chỉ đếm các lời gọi thành công. Một tích hợp ghi log được cấu hình bên ngoài catalog vẫn có thể đọc thông báo lỗi riêng của nhà cung cấp trên exception mà một lời gọi thất bại mang theo, và một tích hợp được đăng ký trước callback riêng của gateway sẽ nhận văn bản của lời gọi thất bại đúng như khi nó đến.
  • Chỉ những log mà cơ chế che ghi qua mới được bao phủ: không bao gồm đầu ra debug của gateway, và không bao gồm log riêng của nhà cung cấp. Metadata của một yêu cầu, các định nghĩa công cụ và các header của nó được ghi log đúng như khi gửi.
  • Một lời gọi có các bản sao không thể che được ghi log với văn bản bị giữ lại. Khi không thể kết nối tới một dịch vụ nhận dạng, không bản sao nào được ghi log ở dạng che một phần: mọi văn bản trong mọi bản sao của lời gọi đó được thay bằng [TEXT_WITHHELD], và bản ghi được chuyển tới log như thường lệ, nên lời gọi vẫn được đếm trong spend log. Log riêng của gateway ghi nhận rằng văn bản của lời gọi đã bị giữ lại. Bản thân lời gọi vẫn được trả lời như thường lệ.

Theo cách catalog kết xuất gateway này, nó không chuyển log tới tích hợp ghi log nào, và spend log của nó không giữ văn bản yêu cầu hay phản hồi nào và không giữ lời gọi thất bại nào. Vì vậy, các bản sao mà cơ chế che bảo vệ là những bản sao mà một tích hợp hoặc một spend log giữ văn bản được cấu hình trên gateway sẽ nhận.

Che dữ liệu trong log hay che dữ liệu

core/data-masking ẩn văn bản được liệt kê khỏi mô hình, và trên gateway này, phần hiện thực của nó tắt việc gateway ghi log nội dung tin nhắn trong khi nó được gắn vào. Bên cạnh nó, việc che dữ liệu trong log sẽ không còn gì để tác động, và người đọc có thể nhầm hai cơ chế là một lớp bảo vệ. Vì vậy gateway từ chối dùng cả hai cùng lúc: khi values.log_masking có liệt kê thứ gì đó, một attachment core/data-masking trên gateway sẽ dừng quá trình build, bằng một assertion của chính Component của gateway. Thêm một attachment tên là masked vào gateway, với phần hiện thực của nó được liên kết trong Manifest, sẽ in ra:

[… omitted: what resolving the lockfile prints, the same halt among it, and a notice that core/referenced-secret declares origin in both of its pillars]
[DEVELOPER_ERROR E0033]
Component/Feature assertions
caused by: Component "core/gateway/litellm" instance "router" assertion "log_masking_not_beside_data_masking": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: "router" lists what to mask in its logs under values.log_masking, and the core/data-masking attachment "masked" is on it too: that attachment's realization turns the gateway's logging of message contents off, so log masking would have nothing left to act on, and a reader could take the two for one protection. Remove values.log_masking to mask what travels, or the "masked" attachment to mask only what is logged

Hãy dùng che dữ liệu trong log khi mô hình phải thấy dữ liệu còn log thì không được giữ lại nó; hãy dùng che dữ liệu khi mô hình cũng không được thấy nó. Cả hai đều đọc cùng patterns và entities, nên một danh sách có cùng ý nghĩa ở cả hai bên.

Nơi trình biên dịch không diễn giải

Trình biên dịch chuyển mẫu và các loại thực thể vào cấu hình của gateway dưới dạng chuỗi. Nó không biên dịch biểu thức, không biết số phiếu hỗ trợ hay một người là gì, và không thấy lưu lượng mà gateway sẽ truyền tải. Mỗi lần dừng mà workspace này có thể gặp — các loại thực thể với socket recognizer chưa được nối, một loại thực thể mà bộ phân tích không nhận diện được trong tiếng Anh, log masking bên cạnh data masking trên cùng một gateway, kết nối tới mô hình được quản lý không mang thông tin xác thực — đều được khai báo bởi chính các thực thể của catalog, dưới dạng một assertion của Component của gateway hoặc của Recipe của nó, và không lần dừng nào dựa trên bất kỳ sự hiểu biết nào về văn bản.

Điều chỉnh ví dụ

  • Chỉ che các mẫu. Bỏ entities khỏi values.log_masking, cùng hai component nhận dạng với các cạnh của chúng và các mục của chúng trong Release; các mẫu được so khớp ngay bên trong gateway và không cần dịch vụ nào trong hai dịch vụ đó.
  • Che thêm các loại thực thể. Thêm chúng vào entities, theo đúng từ vựng của bộ nhận dạng; một loại mà bộ phân tích không nhận dạng được trong tiếng Anh sẽ dừng bản dựng và nêu tên những loại mà nó nhận dạng được.
  • Ẩn cả văn bản khỏi mô hình. Thay values.log_masking bằng một attachment core/data-masking trên gateway, liệt kê cùng các patterns và entities, rồi gắn cách hiện thực của nó trong Manifest.
  • Phục vụ một mô hình thứ hai. Nối một component mô hình khác vào socket models dưới một bí danh riêng, cùng với khóa mà gateway xuất trình cho nó trên kết nối đó; values.model vẫn tiếp tục nêu tên bí danh mà gateway công bố. Việc che dữ liệu áp dụng cho các lời gọi của mọi bí danh mà gateway phục vụ.