OpenAI SDK

SDK Python và TypeScript chính thức của OpenAI hỗ trợ Base URL tùy chỉnh. Trỏ máy khách đến https://api.agtcloud.cn/v1 để gọi điểm vào tương thích Chat Completions và Responses của AGTCloud bằng cùng các phương thức SDK.

Trang này dành cho ứng dụng phía máy chủ. Mã giao diện trình duyệt, gói ứng dụng máy tính và mã di động không thể lưu API Key dài hạn an toàn; không tạo trực tiếp máy khách OpenAI với thông tin xác thực thật trong các môi trường đó.

Chọn Chat hay Responses

Hai điểm vào dùng cùng AGTCloud API Key, nhưng phạm vi mô hình hỗ trợ có thể khác nhau. Xác nhận giao thức mô hình trong danh mục mô hình và thay MODEL_ID trong ví dụ bằng ID đầy đủ.

Chuẩn bị

Trước khi bắt đầu, hãy đảm bảo bạn đã:

• Tạo AGTCloud API Key trên trang API Keys;
• Chuẩn bị ID mô hình hỗ trợ Chat Completions hoặc Responses;
• Dùng môi trường máy chủ đáng tin cậy với Python 3.10+ hoặc Node.js 22+;
• Bật tệp khóa phụ thuộc cho dự án, không tự nâng cấp SDK không kiểm soát trong môi trường sản xuất.

Yêu cầu môi trường có thể thay đổi theo phiên bản SDK. Trước khi nâng cấp, kiểm tra cả phạm vi hỗ trợ chính thức hiện tại và môi trường triển khai dự án.

Cài đặt SDK

python -m pip install openai

Sau khi cài, ghi phiên bản SDK thực tế được phân giải vào tệp khóa dự án. Khi nâng cấp, kiểm tra lại khởi tạo máy khách, kiểu phản hồi và logic xử lý Streaming.

Cấu hình API Key

Nên cung cấp API Key qua biến môi trường phía máy chủ. Thiết lập dưới đây chỉ là ví dụ giữ chỗ an toàn; khi triển khai thực tế có thể dùng dịch vụ quản lý khóa trên đám mây.

export AGTCLOUD_API_KEY="your-api-key"

Tạo máy khách OpenAI

Base URL của máy khách phải là https://api.agtcloud.cn/v1. Không chỉ điền API Origin hoặc thêm /chat/completions hay /responses; SDK nối đường dẫn cụ thể theo phương thức được gọi.

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AGTCLOUD_API_KEY"],
    base_url="https://api.agtcloud.cn/v1",
)

Sử dụng Responses

Responses dùng input cho văn bản hoặc Typed Items; phản hồi thành công chứa trạng thái, Output Items và mức sử dụng Token. SDK cung cấp output_text để tổng hợp đầu ra văn bản.

response = client.responses.create(
    model="MODEL_ID",
    instructions="Hãy trả lời bằng tiếng Việt một cách ngắn gọn và chính xác.",
    input="Nêu ba ý về những vấn đề mà dịch vụ tổng hợp API có thể giải quyết.",
)

print(response.output_text)

output_text phù hợp để đọc văn bản thông thường. Khi xử lý gọi hàm, kết quả tìm kiếm, mục suy luận hoặc kiểu khác, duyệt response.output theo thứ tự, không chỉ giữ kiểu Message. Xem OpenAI Responses Reference để biết cấu trúc đầy đủ.

Sử dụng Chat Completions

Chat Completions dùng messages theo thứ tự. Văn bản thông thường thường nằm trong Assistant Message của Choice đầu tiên.

completion = client.chat.completions.create(
    model="MODEL_ID",
    messages=[
        {
            "role": "developer",
            "content": "Hãy trả lời bằng tiếng Việt một cách ngắn gọn và chính xác.",
        },
        {
            "role": "user",
            "content": "Nêu ba ý về những vấn đề mà dịch vụ tổng hợp API có thể giải quyết.",
        },
    ],
)

print(completion.choices[0].message.content)

Nếu mô hình trả về lời gọi công cụ, message.content có thể trống; hãy kiểm tra message.tool_calls. Xem mô tả trường trong Chat Completions Reference.

Nhận đầu ra dạng luồng

OpenAI SDK cung cấp phản hồi SSE dưới dạng luồng sự kiện có thể lặp. Sự kiện Responses có type rõ ràng; ví dụ dưới chỉ in phần văn bản tăng thêm, còn mã nghiệp vụ phải xử lý trạng thái hoàn tất, thất bại và gián đoạn.

stream = client.responses.create(
    model="MODEL_ID",
    input="Hãy giới thiệu bản thân bằng một câu.",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

Tiếp nối có trạng thái (cần nền tảng hỗ trợ)

Khi mô hình, tài khoản và kênh thượng nguồn hỗ trợ lưu trữ và tiếp nối phản hồi, lưu phản hồi lượt đầu rồi truyền ID đó làm previous_response_id trong yêu cầu tiếp theo:

first = client.responses.create(
    model="MODEL_ID",
    store=True,
    input="Hãy nhớ mã dự án là Aurora.",
)

second = client.responses.create(
    model="MODEL_ID",
    previous_response_id=first.id,
    input="Mã dự án là gì?",
)

print(second.output_text)

Khi dùng previous_response_id, instructions của lượt trước không tự trở thành chỉ dẫn lượt này. Truyền lại các ràng buộc hành vi cần duy trì trong yêu cầu mới.

Nếu đường gọi hiện tại không hỗ trợ lưu trữ hoặc tiếp nối, ứng dụng cần tự quản lý lịch sử và gửi Input cùng Output Items cần giữ trong input lượt sau. Khi giữ lịch sử đầy đủ, không chỉ sao chép văn bản thuần; phải giữ quan hệ thông điệp, suy luận và gọi công cụ cần cho nghiệp vụ.

Thời gian chờ, thử lại và lỗi

OpenAI SDK chuyển lỗi HTTP thành kiểu ngoại lệ tương ứng, tự thử lại có giới hạn cho một số lỗi kết nối, hết thời gian chờ, giới hạn tốc độ và lỗi máy chủ. Ứng dụng production vẫn nên đặt rõ thời gian chờ và số lần thử lại tối đa theo loại yêu cầu để tránh chờ lâu hoặc tiêu thụ lặp.

Không ghi API Key đầy đủ, nội dung yêu cầu nhạy cảm hoặc nội dung người dùng chưa xử lý vào nhật ký. Nếu phản hồi có Request ID, lưu mã này trong nhật ký lỗi để xác định yêu cầu cụ thể.

Kiểm tra hoàn tất

• Base URL máy khách là https://api.agtcloud.cn/v1, không lặp /v1 hoặc thêm đường dẫn điểm cuối cụ thể.
• API Key được đọc từ môi trường máy chủ đáng tin cậy, không xuất hiện trong mã giao diện hoặc quản lý phiên bản.
• MODEL_ID đã được thay bằng mô hình mà API Key hiện tại nhìn thấy và hỗ trợ điểm vào đích.
• Yêu cầu thông thường đọc đúng văn bản, trạng thái và mức sử dụng.
• Mã Streaming phân biệt được phần văn bản tăng thêm, sự kiện hoàn tất và sự kiện lỗi.
• Yêu cầu công cụ hoặc đa phương thức chỉ gửi đến mô hình đã xác nhận hỗ trợ khả năng tương ứng.

Nếu cần thay cấu hình nhà cung cấp cho toàn dự án, đọc tiếp Chuyển đổi SDK chính thức; để chuyển cấu trúc Chat sang Responses, xem Chat → Responses.