Hướng dẫn 2026-09-09

Trỏ OpenAI SDK sang base URL mới

Hai thay đổi là đủ để một ứng dụng OpenAI SDK có sẵn chạy ở đây: base URL và key. Chat completions, responses, streaming và tool calling đều giữ nguyên.

Một ứng dụng đang nói chuyện với OpenAI SDK không cần viết lại để nói chuyện với chúng tôi. Chỉ hai thứ đổi: base URL dùng để dựng client, và key mà nó dùng để xác thực. Mọi thứ ở trên và ở dưới hai dòng đó — lời gọi, messages, các tham số, cách bạn đọc câu trả lời về — vẫn nguyên như bạn đã viết.

Hai dòng phải sửa

Với Python, base URL và key chính là hai tham số dựng nên client. Từ sau constructor trở đi không có gì là của chúng tôi:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://aifromu.com/v1",
    api_key=os.environ["AIFROMU_API_KEY"],
)

resp = client.chat.completions.create(
    model="terra",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

Với Node, vẫn đúng hai thứ ấy, nằm trong object dựng nên client:

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://aifromu.com/v1",
  apiKey: process.env.AIFROMU_API_KEY,
});

const resp = await client.chat.completions.create({
  model: "terra",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(resp.choices[0].message.content);

Key lấy từ portal khách hàng: đăng nhập, mở trang Keys, và key bạn nhận ở đó chính là key client này gửi đi. Cả hai ví dụ đều đọc key từ biến môi trường chứ không viết thẳng vào file, dưới tên AIFROMU_API_KEY, vì một key nằm chung với mã nguồn là một key phải xoay lại ngay khi có người clone repository.

Cả hai endpoint, streaming và tool

Ở đây phục vụ cả /v1/chat/completions lẫn /v1/responses, nên code của bạn đang gọi cái nào thì cứ tiếp tục gọi cái đó — không phải chuyển qua lại giữa hai bên để vào được. Streaming đi qua nguyên vẹn, tool calling cũng vậy: request đi lên đúng hình dạng bạn viết, và các event trả về đúng hình dạng SDK vốn đã phân tích được.

Tên model của bạn sẽ ra sao

Bốn alias — astra, sol, terra và luna — dùng thẳng được, nên một client gọi tên nào là đang xin đúng model trên thẻ đó. Còn một client gọi tên model của OpenAI thì được đọc theo hạng cân của nó: tên có mini hoặc nano phục vụ bằng luna, tên 4-series thường bằng terra, tên frontier hoặc o-series bằng sol, và tên gpt-6 bằng astra. Chính điều đó khiến một dòng model không đụng tới vẫn chạy được ngay ở request đầu tiên sau khi đổi base URL, và cái gì tốn bao nhiêu thì tính đúng bấy nhiêu — theo lớp đã phục vụ request, không theo cái tên đã hỏi.

Một cái tên không khớp vào đâu thì không bị đoán mò: request bị từ chối kèm một thông báo nêu tên bốn model, nên cấu hình sai là thứ bạn nhìn thấy ngay ở lần gọi đầu chứ không phải thứ bạn phát hiện trên hoá đơn. Đoán mò mới là kiểu hỏng tệ hơn, vì nó im lặng — một cái tên bị đọc nhầm lớp sẽ phục vụ người này dưới giá vốn và bắt người kia trả cho năng lực họ chưa từng nhận, mà không request nào nói ra điều đó.

Kiểm xem đã chạy chưa, và đọc lỗi

Lần gọi đầu tiên chính là toàn bộ phần kiểm chứng: câu trả lời về được thì base URL và key đều đúng, và không chỗ nào khác trong file cần đổi. Nếu không về, lời từ chối sẽ nói đó là chuyện của cái nào trong hai thứ — một key không dùng được thì trả lời là key không hợp lệ, còn một model gateway này không phục vụ thì trả lời kèm bốn cái tên nó có phục vụ.

Lỗi ở những chặng còn lại cũng thật như vậy. Khi thượng nguồn từ chối một request, lý do kiểm tra mà họ đưa ra được chuyển thẳng tới bạn chứ không bị gộp phẳng thành một chuỗi mù mờ, nên context quá dài hay một tham số sai đều nói rõ ngay trong câu trả lời. Retry-After được giữ nguyên trên 429, vì đó chính là header mà các SDK dựa vào để giãn nhịp thử lại, và một giới hạn tốc độ chuyển đi mà thiếu nó là một giới hạn client của bạn phải đoán.