Chuyển đổi SDK chính thức
Kết nối ứng dụng SDK OpenAI, Anthropic hoặc Gemini hiện có với AGTCloud và kiểm tra có hệ thống ranh giới tương thích.
Nếu ứng dụng đã dùng SDK OpenAI, Anthropic hoặc Gemini, thường có thể giữ SDK và khung nghiệp vụ, rồi kết nối máy khách với giao thức tương thích cùng loại của AGTCloud. Chuyển đổi không chỉ là đổi địa chỉ: cần kiểm tra đồng thời xác thực, ID mô hình, đường dẫn tự ghép, trường yêu cầu và phân tích phản hồi.
Giữ cùng giao thức
OpenAI, Anthropic Messages và Gemini Generate Content là ba giao thức khác nhau. Thay địa chỉ dịch vụ trong cùng giao thức; nếu đổi cả giao thức, thiết kế và kiểm thử như một lần tái cấu trúc giao diện đầy đủ.
Kiểm kê trước khi chuyển đổi
Ghi lại các khả năng ứng dụng thực sự dùng trước, tránh chỉ kiểm tra yêu cầu văn bản đơn giản nhất.
| Nội dung kiểm tra | Thông tin cần ghi |
|---|---|
| SDK | Tên gói, ngôn ngữ, phiên bản và Client đồng bộ hoặc bất đồng bộ |
| Giao thức | Chat Completions, Responses, Messages hoặc Generate Content |
| Mô hình | ID mô hình hiện tại và danh sách mô hình cho phép trong mã, nếu có |
| Đầu vào | Văn bản, hình ảnh, tệp, chỉ dẫn hệ thống và lịch sử thông điệp |
| Đầu ra | Thuộc tính đọc văn bản nhanh, đối tượng phản hồi đầy đủ và logic phân tích tùy chỉnh |
| Streaming | Kiểu sự kiện, ghép phần tăng thêm và điều kiện kết thúc |
| Công cụ | Định nghĩa, ID lời gọi, phân tích tham số và trả kết quả |
| Độ tin cậy | Thời gian chờ, thử lại, giới hạn tốc độ, nhật ký và chính sách dự phòng |
Thay đổi tối thiểu
Cả ba SDK cần xác nhận cấu hình dưới đây, nhưng cách điền do SDK quyết định.
| Cấu hình | Thao tác chuyển đổi |
|---|---|
| Địa chỉ API | Dùng Origin hoặc Base URL từ hướng dẫn tương ứng, xác nhận SDK có tự thêm đường dẫn phiên bản không |
| API Key | Đọc AGTCloud API Key từ biến môi trường, không ghi vào mã nguồn hoặc kho mã |
| ID mô hình | Dùng mô hình mà API Key hiện tại nhìn thấy và hỗ trợ giao thức đích |
| Phương thức yêu cầu | Giữ phương thức Client của giao thức gốc, như chat.completions.create hoặc messages.create |
| Đọc phản hồi | Đối chiếu AGTCloud Reference để kiểm tra văn bản, công cụ, Usage và cấu trúc lỗi |
Chuyển đổi theo SDK
OpenAI SDK có thể gọi Chat Completions và Responses. Base URL AGTCloud chứa /v1.
| Trước chuyển đổi | Sau chuyển đổi |
|---|---|
| API Key của dịch vụ gốc | Biến môi trường AGTCLOUD_API_KEY |
| Base URL dịch vụ gốc hoặc địa chỉ mặc định SDK | https://api.agtcloud.cn/v1 |
| Tên mô hình gốc | MODEL_ID mà API Key hiện tại nhìn thấy |
| Phương thức Chat hoặc Responses hiện có | Giữ cùng phương thức Client |
Không thêm /v1 lặp
https://api.agtcloud.cn/v1 đã chứa đường dẫn phiên bản. Không cấu hình thành https://api.agtcloud.cn/v1/v1 hoặc điền điểm cuối /chat/completions hay /responses đầy đủ.
Xem OpenAI SDK để biết cài đặt, khởi tạo Client và ví dụ Python, TypeScript đầy đủ.
Khi không thể chỉ đổi ba cấu hình
Các tình huống sau cần sửa mã nghiệp vụ, không chỉ thay Base URL, Key và mô hình:
- Ứng dụng chuyển từ Chat Completions sang Responses;
- Ứng dụng chuyển giữa giao thức OpenAI, Anthropic hoặc Gemini;
- Mã phụ thuộc trực tiếp vào lớp phản hồi, thuộc tính tiện ích hoặc sự kiện luồng của một SDK;
- Gọi công cụ dùng định nghĩa và cấu trúc trả kết quả riêng của giao thức;
- Khối nội dung đa phương thức, chỉ dẫn hệ thống hoặc tên vai trò thay đổi;
- SDK tự nối đường dẫn trong khi dự án gốc truyền URL điểm cuối đầy đủ;
- Ứng dụng phụ thuộc khám phá mô hình, tải tệp hoặc công cụ được lưu trữ riêng của dịch vụ gốc.
Kiểm tra kết quả chuyển đổi
Kiểm tra yêu cầu văn bản tối thiểu
Gửi yêu cầu không dùng Streaming, công cụ hoặc nội dung đa phương thức trước. Xác nhận yêu cầu đến đúng địa chỉ API và đọc được phản hồi văn bản.
Khôi phục các khả năng cần dùng trong môi trường production
Khôi phục lần lượt Streaming, gọi công cụ, đầu ra có cấu trúc, đa phương thức và trạng thái nhiều lượt. Mỗi lần chỉ thêm một khả năng để dễ xác định khác biệt.
Kiểm tra đường xử lý không thành công
Ít nhất kiểm tra API Key không hợp lệ, ID mô hình sai, hết thời gian chờ, giới hạn tốc độ và mất kết nối. Xác nhận ứng dụng đọc được mã trạng thái cùng thông tin lỗi và không thử lại vô hạn.
So sánh kết quả nghiệp vụ
Không chỉ kiểm tra HTTP 200. So sánh đồng thời nội dung văn bản, tham số công cụ, lý do kết thúc, Usage, điều kiện kết thúc luồng và Request ID trong nhật ký.
Chuyển đổi theo giai đoạn và hoàn tác
- Giữ cấu hình riêng cho Provider mới và cũ, không rải địa chỉ và tên mô hình trong mã nghiệp vụ.
- Cho lưu lượng phát triển hoặc thử nghiệm dùng AGTCloud trước, rồi mở rộng dần.
- Ghi tỷ lệ thành công, độ trễ, loại lỗi và khác biệt chức năng ở từng giai đoạn.
- Giữ cấu hình Provider gốc cùng công tắc dự phòng có kiểm soát, chỉ dọn cấu hình cũ khi đã ổn định.
Không dựa vào việc bỏ qua âm thầm
Một số triển khai tương thích có thể chấp nhận trường không biết nhưng không thực hiện khả năng tương ứng. Khi kiểm tra, quan sát kết quả thực tế và cấu trúc phản hồi, không chỉ dựa vào mã trạng thái để kết luận trường có hiệu lực.
Bước tiếp theo
- Xem Tổng quan SDK để chọn hướng dẫn tương ứng;
- Xem API Key, Base URL và xác thực;
- Nếu định chuyển Chat sang Responses, đọc tiếp Chat Completions → Responses;
- Khi gặp mã trạng thái hoặc yêu cầu thất bại, xem Lỗi và khắc phục sự cố.