← Quay lại

Cách gọi mô hình qua API tương thích OpenAI

2026-11-11

Tóm tắt

Chỉ cần cấu hình API key của nhà cung cấp, base URL và ID mô hình chính xác là bạn có thể gọi mô hình qua API tương thích OpenAI bằng OpenAI SDK. Bài viết hướng dẫn gửi yêu cầu Chat Completions với Python và cURL, nhận phản hồi streaming và tìm nguyên nhân lỗi. Với hình ảnh, video và giọng nói, bạn cần dùng endpoint dành riêng cho từng loại đầu ra.

Để gọi mô hình qua API tương thích OpenAI, hãy cấu hình client của OpenAI SDK với khóa API (API key) và địa chỉ API gốc (base URL) của nhà cung cấp, rồi gửi yêu cầu Chat Completions với ID mô hình chính xác. Nếu dùng cURL, bạn gửi cùng yêu cầu trực tiếp qua HTTP, gồm xác thực Bearer, mảng tin nhắn dạng JSON và ID mô hình.

Bắt đầu bằng một yêu cầu văn bản ngắn. Khi đã nhận được câu trả lời, hãy bật streaming để nhận văn bản từng phần hoặc thêm các tùy chọn riêng của ứng dụng. Cách này giúp khoanh vùng lỗi cấu hình dễ hơn so với việc thêm công cụ, hình ảnh và lịch sử hội thoại dài ngay từ đầu.

1. Thiết lập đúng ba thông số kết nối

API tương thích OpenAI sử dụng cấu trúc yêu cầu và phản hồi quen thuộc của OpenAI trên dịch vụ của nhà cung cấp. Dùng OpenAI SDK không có nghĩa là yêu cầu phải gửi đến OpenAI; base URL bạn cấu hình quyết định máy chủ nhận yêu cầu. Với AIAdapter, bạn có thể dùng lại cùng client và API key của tài khoản khi đổi giữa các mô hình chat được hỗ trợ, nhờ đó quản lý cấu hình kết nối riêng với việc chọn mô hình.

Tài liệu API của AIAdapter quy định:

SDK tự nối /chat/completions vào base URL. Giữ nguyên /v1 và không điền toàn bộ địa chỉ endpoint vào base_url.

Chọn một mô hình chat từ danh mục mô hình. Các ví dụ bên dưới dùng mô hình Qwen3.5-Plus với ID aliyun-bailian/qwen3.5-plus. Hãy sao chép nguyên ID thay vì chỉ nhập tên dòng mô hình như Qwen.

Tạo khóa tại Console → API Keys. Lưu khóa ở phía máy chủ bằng biến môi trường hoặc dịch vụ quản lý secrets, không nhúng vào JavaScript ở frontend. Khóa AIAdapter dùng để xác thực với AIAdapter; bạn không thể dùng khóa của tài khoản OpenAI để thay thế.

2. Chuẩn bị Python và biến môi trường

SDK OpenAI cho Python hiện tại yêu cầu Python 3.10 trở lên. Cài đặt bằng trình thông dịch sẽ chạy tập lệnh của bạn:

python -m pip install --upgrade openai

Thiết lập các biến môi trường sau trong terminal, thay giá trị khóa mẫu bằng khóa tài khoản của bạn.

macOS, Linux hoặc Bash:

export AIADAPTER_API_KEY="your-aiadapter-api-key"
export AIADAPTER_MODEL_ID="aliyun-bailian/qwen3.5-plus"

Windows PowerShell:

$env:AIADAPTER_API_KEY = "your-aiadapter-api-key"
$env:AIADAPTER_MODEL_ID = "aliyun-bailian/qwen3.5-plus"

Các thiết lập này chỉ áp dụng cho phiên terminal hiện tại. Chạy Python từ chính terminal đó để chương trình nhận được các biến môi trường. Khi triển khai ứng dụng, hãy cấu hình các biến trong phần quản lý secrets của nền tảng hosting. Tránh nhập khóa trên máy dùng chung vì lịch sử shell có thể làm lộ khóa.

3. Gửi yêu cầu hội thoại đầu tiên

Lưu ví dụ này thành call_model.py:

import os
from openai import OpenAI

with OpenAI(
    api_key=os.environ["AIADAPTER_API_KEY"],
    base_url="https://api.aiadapter.com/v1",
    timeout=60.0,
    max_retries=0,
) as client:
    completion = client.chat.completions.create(
        model=os.environ["AIADAPTER_MODEL_ID"],
        messages=[
            {"role": "user", "content": "Explain an API in two sentences."}
        ],
    )
    print(completion.choices[0].message.content)

Chạy bằng python call_model.py.

SDK tự tạo header xác thực và chuyển dữ liệu yêu cầu sang định dạng gửi qua API. messages chứa nội dung hội thoại; model chỉ định mô hình cần gọi. Với phản hồi văn bản thông thường, câu trả lời nằm trong choices[0].message.content, và chương trình sẽ in nội dung đó.

Yêu cầu đầu tiên này bỏ qua các trường tùy chọn về lấy mẫu, suy luận và giới hạn độ dài đầu ra. Khi lệnh gọi cơ bản đã hoạt động, thêm các trường theo tài liệu của mô hình được chọn. Một số mô hình dùng max_tokens, trong khi mô hình khác dùng max_completion_tokens hoặc các tham số điều khiển khác.

max_retries=0 tắt tính năng tự động thử lại của SDK để dễ tìm nguyên nhân lỗi ở lần gọi đầu tiên. timeout=60.0 đặt thời gian chờ 60 giây cho các thao tác mạng, không giới hạn tổng thời gian chạy của tập lệnh ở 60 giây. Khi chạy ứng dụng trong môi trường production, hãy chọn timeout phù hợp và giới hạn số lần thử lại.

4. Gửi yêu cầu tương đương bằng cURL

Dùng lệnh Bash này để kiểm tra yêu cầu HTTP mà không qua SDK Python:

curl https://api.aiadapter.com/v1/chat/completions \
  -H "Authorization: Bearer $AIADAPTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "aliyun-bailian/qwen3.5-plus",
    "messages": [
      {"role": "user", "content": "Explain an API in two sentences."}
    ]
  }'

Ở đây, bạn cung cấp toàn bộ endpoint vì cURL không nối thêm đường dẫn như SDK. Tùy chọn -d gửi một yêu cầu POST. Đọc JSON trả về, gồm cả thông báo lỗi nếu yêu cầu thất bại.

Nếu gọi bằng cURL thành công nhưng Python báo lỗi, hãy đối chiếu các biến môi trường, phiên bản SDK đã cài và cấu hình client thực tế. Nếu cả hai đều lỗi, kiểm tra API key, endpoint, ID mô hình và số dư tài khoản trước khi đổi prompt.

5. Nhận phản hồi từng phần với streaming

Với mô hình chat hỗ trợ streaming, đặt stream=True và đọc văn bản từ delta.content trong từng phần dữ liệu trả về (chunk). Lưu ví dụ sau thành một tập lệnh riêng và dùng cùng các biến môi trường:

import os
from openai import OpenAI

with OpenAI(
    api_key=os.environ["AIADAPTER_API_KEY"],
    base_url="https://api.aiadapter.com/v1",
    timeout=60.0,
    max_retries=0,
) as client:
    with client.chat.completions.create(
        model=os.environ["AIADAPTER_MODEL_ID"],
        messages=[{"role": "user", "content": "Explain an API in two sentences."}],
        stream=True,
    ) as stream:
        for chunk in stream:
            if chunk.choices:
                text = chunk.choices[0].delta.content
                if text:
                    print(text, end="", flush=True)
    print()

Theo tài liệu AIAdapter, phản hồi chat dạng streaming dùng Server-Sent Events. Các điều kiện trong ví dụ bỏ qua chunk không chứa văn bản mới, chẳng hạn chunk điều khiển hoặc chunk chỉ có dữ liệu về lượng sử dụng. Streaming giúp bạn nhận và hiển thị văn bản từng phần, nhưng không thay đổi yêu cầu đầu vào của mô hình.

6. Chẩn đoán lỗi trước khi thêm tính năng

Kết hợp trạng thái HTTP với thông báo lỗi trả về:

Trong Python, bắt openai.APIStatusError để xem status_code và response. Bắt openai.APIConnectionError cho lỗi kết nối. Lỗi trong luồng cũng có thể phát sinh ngoại lệ openai.APIError, nên cần xử lý ngoại lệ cả khi tạo yêu cầu lẫn khi lặp qua các chunk. Không ghi khóa và prompt nhạy cảm vào nhật ký chẩn đoán.

Câu hỏi thường gặp

Tương thích OpenAI có nghĩa là mọi endpoint OpenAI đều hoạt động không?

Không. Bạn chỉ dùng được những endpoint mà nhà cung cấp đã triển khai. Hướng dẫn này dùng Chat Completions vì endpoint đó có trong tài liệu AIAdapter. SDK có thể cung cấp thêm Responses, tải tệp, trợ lý hoặc các chức năng khác, nhưng không phải nhà cung cấp nào cũng hỗ trợ chúng. Hãy chọn phương thức SDK tương ứng với API được mô tả trong tài liệu của nhà cung cấp. Trước khi thêm tính năng chat nâng cao, kiểm tra các tham số về gọi công cụ, suy luận và đầu ra có cấu trúc mà mô hình chấp nhận.

Có thể đổi mô hình mà không sửa client Python không?

Nếu mô hình mới dùng cùng endpoint Chat Completions và cơ chế xác thực, bạn có thể giữ nguyên client và chỉ thay ID mô hình. Tập lệnh đọc ID từ AIADAPTER_MODEL_ID, nên bạn chọn mô hình chat khác bằng cách đổi biến môi trường này. Hãy kiểm tra thêm các tham số được hỗ trợ, giới hạn ngữ cảnh và cách xử lý phản hồi của mô hình mới. Trước tiên, dùng cùng một tin nhắn ngắn để kiểm tra, rồi mới thêm lại công cụ, yêu cầu định dạng và lịch sử hội thoại dài của ứng dụng.

Ví dụ hội thoại này có thể tạo hình ảnh hoặc video không?

Dùng thao tác phù hợp với đầu ra cần tạo. AIAdapter có tài liệu cho /v1/images/generations để tạo hình ảnh, /v1/video/generations cho tác vụ video và /v1/audio/speech để tổng hợp giọng nói. Tạo video cần gửi tác vụ trước, rồi truy vấn định kỳ /v1/video/generations/{id}. Mô hình thị giác-ngôn ngữ hiểu hình ảnh khác với mô hình tạo hình ảnh. Hãy dùng trường yêu cầu và cách xử lý đầu ra của mô hình tương ứng cho từng thao tác, thay vì đưa ID mô hình video vào ví dụ hội thoại.

Thử lại ảnh hưởng thế nào đến lệnh gọi thất bại hoặc hết thời gian chờ?

SDK OpenAI cho Python mặc định thử lại hai lần đối với một số lỗi kết nối và lỗi HTTP. Hướng dẫn này tắt hành vi đó trong lần kiểm tra đầu tiên để dễ truy vết lỗi. Hết thời gian chờ không chứng minh máy chủ chưa xử lý, nên gửi lại yêu cầu tạo nội dung có thể gây xử lý trùng lặp. Giới hạn số lần thử lại, kiểm tra trạng thái yêu cầu hoặc tác vụ nếu có và tính cả các lần gửi bổ sung. Nếu luồng bị ngắt sau khi đã trả về một phần văn bản, hãy xử lý rõ ràng phần đầu ra đã nhận.

Làm sao kiểm tra chi phí của yêu cầu đầu tiên?

Trước khi gọi, xem mức giá hiện tại và đơn vị tính phí trong danh mục mô hình và bảng giá và trên trang chi tiết của mô hình được chọn. Với hội thoại tính phí theo token, cả đầu vào lẫn đầu ra đều ảnh hưởng đến chi phí; trường tùy chọn và câu trả lời dài hơn có thể thay đổi lượng sử dụng. Khi phản hồi có dữ liệu sử dụng, hãy đối chiếu với bản ghi thanh toán trong console. Hình ảnh, video và giọng nói có thể dùng đơn vị tính phí khác, vì vậy không ước tính chi phí của chúng từ giá token hội thoại.

Khi yêu cầu ngắn đã trả về câu trả lời, hãy dùng cấu hình đó để tích hợp vào ứng dụng. Nếu chưa có API key, hãy tạo tài khoản và bắt đầu gọi API từ phía máy chủ.

aliyun-bailian/qwen3.5-plus

FAQ

Cách gọi mô hình qua API tương thích OpenAI

Chỉ cần cấu hình API key của nhà cung cấp, base URL và ID mô hình chính xác là bạn có thể gọi mô hình qua API tương thích OpenAI bằng OpenAI SDK. Bài viết hướng dẫn gửi yêu cầu Chat Completions với Python và cURL, nhận phản hồi streaming và tìm nguyên nhân lỗi. Với hình ảnh, video và giọng nói, bạn cần dùng endpoint dành riêng cho từng loại đầu ra.