Bedrock qua LiteLLM
Sử dụng trang này khi tổ chức của bạn định tuyến Codex tới Amazon Bedrock qua LiteLLM. Nếu đã có gateway LiteLLM, hãy kết nối Codex trước. Chỉ triển khai LiteLLM khi tổ chức của bạn cần gateway mới.
Các sản phẩm gateway khác tuân theo cùng yêu cầu đối với gateway và quy trình kết nối Codex.
Kết nối với gateway hiện có
Lấy các giá trị sau từ quản trị viên gateway của bạn:
- URL cơ sở HTTPS, chẳng hạn như
https://gateway.example.com/v1. - Bí danh mô hình mà LiteLLM định tuyến tới mô hình Bedrock đã được phê duyệt.
- ID nhà cung cấp để dùng trong cấu hình Codex.
- Thông tin xác thực gateway với phạm vi giới hạn hoặc trình trợ giúp xác thực trả về thông tin đó.
- Mọi danh mục mô hình được phân phối cùng cấu hình của tổ chức.
Sau đó hoàn tất kết nối theo thứ tự sau:
- Yêu cầu nhóm phụ trách gateway xác nhận rằng gateway phục vụ
POST /v1/responses, truyền phản hồi theo luồng, duy trì các lượt tiếp theo và lệnh gọi công cụ, đồng thời định tuyến bí danh đã được phê duyệt. Xem Khả năng tương thích của gateway. - Làm theo Kết nối với gateway để cấu hình nhà cung cấp, mô hình và thông tin xác thực.
- Xác minh nhà cung cấp và bí danh đang hoạt động, gửi câu lệnh ngắn
gateway-oktrong hướng dẫn kết nối và xác nhận rằng bản ghi LiteLLM hiển thị đúng người dùng và bí danh dự kiến. - Để phân phối trong toàn tổ chức, hãy tiếp tục với Triển khai Codex qua gateway.
Thông tin xác thực gateway dùng để xác thực bạn với LiteLLM. Gateway tự quản lý thông tin xác thực Bedrock; bạn không cần sao chép những thông tin xác thực đó sang máy trạm.
Chuẩn bị gateway
Chỉ sử dụng phần này khi bạn cần tạo gateway LiteLLM trước khi kết nối Codex.
Trước khi triển khai
Xác nhận rằng bạn có:
- Quyền triển khai kiến trúc LiteLLM đã được phê duyệt trong môi trường AWS của bạn.
- Quyền truy cập Bedrock vào các mô hình hoặc hồ sơ suy luận mà bạn sẽ định tuyến.
- Image LiteLLM và phương án triển khai đã được rà soát.
- Tên máy chủ HTTPS và chứng chỉ đáng tin cậy.
- Dải mạng máy khách được giới hạn.
Với ví dụ Runtime bên dưới, danh tính AWS của gateway cần bedrock:InvokeModel cho hồ sơ suy luận đã chọn và dự án mặc định của tài khoản. Xem hướng dẫn thiết lập GPT-6 Sol của AWS để biết các quyền bắt buộc.
Kiến trúc
Triển khai đặt LiteLLM giữa Codex và Bedrock, với HTTPS tại ranh giới máy khách. Bộ cân bằng tải và LiteLLM nằm bên trong ranh giới gateway của tổ chức; thông tin xác thực nhà cung cấp được giữ trên gateway.
Giới hạn truy cập vào chỉ cho các máy khách được phê duyệt, giữ các cổng cơ sở dữ liệu và bộ nhớ đệm trong mạng riêng, đồng thời chỉ cấp cho gateway các quyền Bedrock cần thiết. Cố định image triển khai bằng digest để việc khởi động lại không âm thầm thay đổi bản triển khai.
Câu lệnh, đoạn trích mã nguồn và kết quả công cụ đi qua gateway và có thể được ghi vào nhật ký. Quyết định chính sách lưu giữ, truy cập và che dữ liệu nhạy cảm trước khi bật ghi nhật ký yêu cầu. MCP servers và plugin có kết nối và xác thực riêng; cấu hình gateway này không cấu hình chúng.
Các bước kiểm tra triển khai
Hoàn thành các bước kiểm tra này theo thứ tự trước khi bàn giao gateway cho nhà phát triển:
| Bước kiểm tra | Kết quả |
|---|---|
| Triển khai proxy cùng các thành phần cơ sở dữ liệu và bộ nhớ đệm phụ thuộc trong mạng riêng. | URL cơ sở HTTPS ổn định kết thúc bằng /v1, với xác thực Bedrock do gateway quản lý. |
| Cấu hình tuyến mô hình và danh mục máy khách tương ứng. | Bí danh ổn định dành cho Codex được ánh xạ tới đích Bedrock dự kiến. |
| Xác minh khả năng hỗ trợ Responses. | Phản hồi POST /v1/responses truyền theo luồng kết thúc bằng response.completed. |
| Cấp thông tin xác thực thử nghiệm. | Khóa ảo riêng cho từng người dùng, giới hạn ở bí danh, có thời hạn, ngân sách và giới hạn tốc độ. |
| Kết nối một nhà phát triển. | Cấu hình nhà cung cấp Codex và câu lệnh ngắn đã được xác minh qua gateway. |
Các phần bên dưới trình bày từng bước kiểm tra. Để triển khai trong môi trường sản xuất, hãy kiểm thử cả các lượt tiếp theo, công cụ và việc thu hồi thông tin xác thực.
Chọn tuyến Bedrock
Tuyến thượng nguồn của LiteLLM xác định điểm cuối Bedrock, mã định danh mô hình và phương thức xác thực. Giữ các lựa chọn này đồng bộ khi triển khai hoặc thay đổi gateway.
Sử dụng Bedrock Runtime cho cấu hình mới. Ví dụ bên dưới sử dụng điểm cuối Responses tương thích với OpenAI của dịch vụ này.
Xem tích hợp Bedrock Mantle của LiteLLM để biết tuyến thay thế.
Để có ví dụ triển khai trên AWS, hãy dùng triển khai tham khảo LiteLLM trên ECS đã được cố định phiên bản. Triển khai đó sử dụng Bedrock Runtime và làm mới xác thực từ vai trò tác vụ ECS. Thực hiện các bước triển khai và xác thực cùng nhau, đồng thời đối chiếu các yêu cầu cho môi trường sản xuất với chính sách mạng, TLS, ghi nhật ký và lưu giữ tài nguyên của bạn.
Dù chọn tuyến nào, hãy xác minh tổ hợp phiên bản gateway, điểm cuối thượng nguồn và mô hình đã triển khai theo Khả năng tương thích của gateway. Việc mô hình thượng nguồn xuất hiện trong danh sách mô hình của gateway không xác nhận rằng hành vi truyền theo luồng, tiếp nối hội thoại và công cụ của mô hình hoạt động với Codex.
Cấu hình tuyến mô hình Runtime
Ánh xạ bí danh ổn định dành cho Codex tới mô hình thượng nguồn đã được phê duyệt. Xác nhận quyền truy cập trong tài khoản AWS và Khu vực của bạn trước khi dùng ví dụ Runtime này.
model_list:
- model_name: company-coding-model
litellm_params:
model: openai/global.openai.gpt-6-sol
api_key: os.environ/AWS_BEARER_TOKEN_BEDROCK
api_base: https://bedrock-runtime.us-east-1.amazonaws.com/openai/v1Cung cấp API key Bedrock hợp lệ dưới dạng AWS_BEARER_TOKEN_BEDROCK qua hệ thống quản lý bí mật. Với khóa có thời hạn ngắn, hãy cấp khóa thay thế trước khi hết hạn, cập nhật môi trường tiến trình gateway và khởi động lại hoặc triển khai lại các worker sử dụng khóa đó. Thay vào đó, triển khai tham khảo ECS làm mới thông tin xác thực ngay trong tiến trình từ vai trò tác vụ; hãy dùng cấu hình và điểm vào của triển khai đó cùng nhau.
Tiền tố openai/ chọn bộ điều hợp tương thích với OpenAI của LiteLLM; api_base đã cấu hình gửi yêu cầu tới Bedrock Runtime. Hồ sơ suy luận Global có thể định tuyến yêu cầu ra ngoài Khu vực nguồn. Chọn hồ sơ và Khu vực đáp ứng các quyền AWS và yêu cầu về nơi lưu trú dữ liệu của bạn, đồng thời thay cả hai giá trị khi cần.
Máy khách gửi company-coding-model; LiteLLM sử dụng tuyến thượng nguồn đã cấu hình. Bí danh tùy chỉnh này yêu cầu danh mục máy khách tương ứng được mô tả tiếp theo. Gateway thông thường không kế thừa các điều chỉnh siêu dữ liệu của nhà cung cấp Bedrock tích hợp sẵn.
Chuẩn bị danh mục máy khách
Với ví dụ GPT-6 Sol/Runtime này dùng Codex 0.158.0, hãy bắt đầu bằng mục gpt-6-sol đầy đủ trong danh mục mô hình của phiên bản đó. Áp dụng tất cả các chỉnh sửa sau cho mục này:
| Trường | Chỉnh sửa bắt buộc |
|---|---|
slug |
Đặt thành "company-coding-model", khớp với bí danh LiteLLM. |
visibility |
Đặt thành "list". |
availability_nux |
Đặt thành null. |
upgrade |
Đặt thành null. |
use_responses_lite |
Đặt thành false. |
tool_mode |
Đặt thành null. |
supported_reasoning_levels |
Xóa mục có effort là "ultra"; giữ lại các mục khác. |
additional_speed_tiers |
Đặt thành []. |
service_tiers |
Đặt thành []. |
default_service_tier |
Đặt thành null. |
web_search_tool_type |
Đặt thành "text". |
multi_agent_version |
Đặt thành "v1". |
supports_search_tool |
Đặt thành false cho Runtime. |
Giữ nguyên các trường còn lại, bao gồm chỉ dẫn và giới hạn ngữ cảnh của mô hình. Giữ mục đã chỉnh sửa trong mảng models cấp cao nhất của danh mục. Các thay đổi này phản ánh những điều chỉnh siêu dữ liệu Bedrock và hạn chế tìm kiếm của Runtime đã phát hành. Kiểm tra lại chúng với mã nguồn tương ứng khi thay đổi phiên bản máy khách hoặc mô hình thượng nguồn.
Phân phối tệp JSON đầy đủ và cấu hình model_catalog_json theo Triển khai Codex qua gateway. Giữ web_search = "disabled" trong cấu hình máy khách Runtime. Xác minh danh mục đã chỉnh sửa qua gateway trước khi phân phối cho nhiều người dùng hơn.
Xác minh khả năng hỗ trợ Responses
Cung cấp POST /v1/responses tại điểm cuối HTTPS phía máy khách. Cấu hình bộ cân bằng tải và mọi proxy ngược để chuyển tiếp các sự kiện truyền theo luồng mà không lưu đệm. Duy trì các lượt tiếp theo và kết quả gọi hàm. Chỉ có điểm cuối Chat Completions hoạt động là chưa đủ cho kết nối này.
Hoàn thành các bước kiểm tra trong Khả năng tương thích của gateway trước khi phân phối cấu hình máy khách. Kiểm thử qua cùng tên máy chủ, các biện pháp kiểm soát mạng và đường xác thực mà người dùng sẽ sử dụng.
Cấp thông tin xác thực thử nghiệm
Tạo khóa ảo LiteLLM với phạm vi giới hạn cho một người dùng thử nghiệm. Giới hạn khóa ở bí danh đã được phê duyệt và cấu hình thời hạn, giới hạn tốc độ cùng ngân sách. Xem tài liệu về khóa ảo của LiteLLM để biết các biện pháp kiểm soát áp dụng.
Phân phối khóa qua quy trình quản lý bí mật hoặc trình trợ giúp xác thực. Không cung cấp khóa quản trị LiteLLM cho người dùng hoặc nhúng thông tin xác thực gateway vào config.toml.
Xác minh kết nối của người dùng
Hoàn thành các bước kiểm tra này trước khi mở rộng quyền truy cập:
- Xác nhận chứng chỉ HTTPS khớp với tên máy chủ gateway và dịch vụ hoạt động bình thường.
- Kết nối một người dùng theo Kết nối với gateway.
- Chạy một câu lệnh ngắn, một lượt tiếp theo và một tác vụ công cụ chỉ đọc.
- Xác nhận bản ghi gateway hiển thị danh tính, bí danh và tuyến thượng nguồn dự kiến mà không làm lộ thông tin xác thực hoặc nội dung câu lệnh nhạy cảm.
- Kiểm thử việc hết hạn hoặc thu hồi thông tin xác thực và xác nhận rằng các bí danh mô hình không được cấp quyền bị từ chối.
Lưu phiên bản image đã triển khai, cấu hình tuyến và kết quả kiểm thử cùng hồ sơ triển khai. Tiếp tục với Triển khai Codex qua gateway để phân phối cho nhóm và vận hành lâu dài.
Khắc phục sự cố kết nối
Dựa vào lớp xảy ra lỗi để khoanh vùng vấn đề:
| Triệu chứng | Nội dung cần kiểm tra |
|---|---|
| HTTPS thất bại trước khi suy luận | DNS, tên máy chủ trong chứng chỉ, tình trạng bộ cân bằng tải và các mạng máy khách được phép. |
Gateway trả về 401 hoặc 403 |
Dùng nhật ký gateway để phân biệt thông tin xác thực người dùng bị từ chối với lỗi xác thực hoặc quyền truy cập Bedrock thượng nguồn. |
| Không tìm thấy mô hình được yêu cầu | Xác nhận chính xác bí danh phía máy khách và ánh xạ của bí danh đó tới mô hình thượng nguồn hoặc hồ sơ suy luận. |
| Yêu cầu bị chặn trước khi tới LiteLLM | Kiểm tra nhật ký bộ cân bằng tải và tường lửa ứng dụng web, bao gồm giới hạn phần thân yêu cầu. Duy trì các biện pháp kiểm soát bảo mật trong khi kiểm thử các yêu cầu Codex tiêu biểu. |
| Văn bản hoạt động nhưng lượt hội thoại không hoàn tất | Kiểm tra bộ đệm truyền theo luồng, thời gian chờ, sự kiện kết thúc và các bước kiểm tra lượt tiếp theo cùng lệnh gọi công cụ trong Khả năng tương thích của gateway. |
| Yêu cầu thượng nguồn hết thời gian chờ | Kiểm tra tính khả dụng của mô hình tại Khu vực nguồn, cấu hình định tuyến, hạn mức và nhật ký gateway trước khi thay đổi thời gian chờ. |
Kiểm thử lại cùng đường kết nối của người dùng sau khi khắc phục. Kiểm tra tình trạng gateway thành công không xác minh được yêu cầu suy luận đã xác thực hoặc một lượt Codex hoàn chỉnh.