Tổng quan SDK
Chọn SDK máy khách OpenAI, Anthropic hoặc Gemini theo giao thức và kiểm tra trước khi kết nối.
AGTCloud cung cấp điểm vào tương thích OpenAI, Anthropic và Gemini. Dự án phía máy chủ đang dùng SDK chính thức tương ứng thường có thể giữ cách gọi chính, rồi thay địa chỉ API, API Key và ID mô hình bằng cấu hình AGTCloud.
SDK chỉ tổ chức yêu cầu theo giao thức tương ứng. Trước khi chọn, xác nhận giao thức mô hình đích hỗ trợ, không đánh giá khả năng tương thích chỉ theo tên mô hình.
Chọn SDK máy khách
| SDK | Giao thức tương ứng | Xác thực | Tình huống phù hợp |
|---|---|---|---|
| OpenAI SDK | Chat Completions, Responses | Bearer API Key | Dự án OpenAI SDK hiện có hoặc cần hội thoại, Typed Items, đầu ra dạng luồng và gọi công cụ |
| Anthropic SDK | Anthropic Messages | x-api-key và Header phiên bản | Dự án Anthropic Messages hiện có hoặc cần Content Blocks và cấu trúc công cụ Anthropic |
| Gemini SDK | Gemini Generate Content | Bearer API Key | Dự án Gemini SDK hiện có hoặc cần contents, parts và cấu trúc nội dung gốc Gemini |
SDK không tự chuyển đổi giao thức
messages hoặc input của OpenAI, Content Blocks của Anthropic, contents và parts của Gemini là các cấu trúc dữ liệu khác nhau. Dùng hướng dẫn giao thức phù hợp với mã nghiệp vụ hiện tại; nếu cần tái cấu trúc giữa các giao thức, đọc Chuyển đổi SDK chính thức trước.
Khác biệt chính giữa ba giao thức
| Nội dung so sánh | OpenAI SDK | Anthropic SDK | Gemini SDK |
|---|---|---|---|
| Điểm vào chính | Chat Completions, Responses | Messages | Generate Content |
| Đầu vào hội thoại | messages hoặc input | messages và Content Blocks | contents và parts |
| Đầu ra văn bản thông thường | Chat Message hoặc Responses Output Items | Khối nội dung content | candidates[].content.parts |
| Cấu trúc luồng | Chat Delta hoặc sự kiện response.* | Sự kiện Messages SSE | Stream Generate Content |
| Cấu trúc công cụ | Function Tools và công cụ tích hợp Responses | tool_use, tool_result | functionCall, functionResponse |
Tham khảo API Reference tương ứng để biết đầy đủ trường, giá trị liệt kê và cấu trúc phản hồi. Hướng dẫn SDK tập trung vào cài đặt, khởi tạo máy khách và đọc kết quả, không trình bày lại toàn bộ Schema.
Chuẩn bị trước khi kết nối
Tạo API Key
Tạo AGTCloud API Key trên trang API Keys và lưu trong biến môi trường phía máy chủ hoặc dịch vụ quản lý khóa.
Không đưa API Key thật vào mã trình duyệt, gói cài đặt di động, kho mã công khai, ảnh chụp màn hình hoặc nhật ký.
Xác nhận mô hình và giao thức
Sao chép ID mô hình đầy đủ từ danh mục mô hình, xác nhận mô hình hỗ trợ giao thức và khả năng bạn định dùng.
Kênh này dùng MODEL_ID làm giá trị giữ chỗ cho mô hình. Phải thay bằng ID mô hình mà API Key hiện tại nhìn thấy trước khi gọi thực tế.
Chọn môi trường chạy phía máy chủ
SDK Python và TypeScript đều cần chạy trong môi trường máy chủ đáng tin cậy. Cài SDK ổn định hiện tại và cố định phiên bản thực tế bằng tệp khóa phụ thuộc của dự án.
Thứ tự kiểm tra đề xuất
- Cài SDK và xác nhận ứng dụng đọc được API Key.
- Cấu hình Base URL trong hướng dẫn, không điền đường dẫn điểm cuối nghiệp vụ đầy đủ.
- Gửi một yêu cầu không dùng luồng với văn bản thuần và số trường tối thiểu.
- Kiểm tra kết quả văn bản, trạng thái kết thúc và mức sử dụng Token.
- Sau đó kiểm tra Streaming, công cụ, đa phương thức hoặc đầu ra có cấu trúc theo nhu cầu.
- Thêm nhật ký và thử lại có kiểm soát cho thời gian chờ, giới hạn tốc độ và lỗi máy chủ.
Có giao thức không có nghĩa mô hình hỗ trợ mọi khả năng
Các mô hình trong cùng giao thức có thể khác nhau về phương thức đầu vào, công cụ, đầu ra có cấu trúc và khả năng dùng luồng. Nếu báo trường không được hỗ trợ hoặc mô hình không khả dụng, kiểm tra thông tin mô hình và API Reference tương ứng trước.
Bước tiếp theo
- Dùng OpenAI SDK để gọi Chat Completions hoặc Responses.
- Dùng Anthropic SDK để gọi Messages.
- Dùng Gemini SDK để gọi Generate Content.
- Dự án dùng SDK chính thức có thể xem danh sách kiểm tra trong Chuyển đổi SDK chính thức.
- Khi yêu cầu thất bại, xem Lỗi và khắc phục sự cố.