Bỏ qua, tới nội dung chính

SDK và thư viện

SDK và thư viện

Chat Tự Động chưa phát hành SDK riêng và trong phần lớn trường hợp điều này không cần thiết. Endpoint gọi model được thiết kế tương thích chuẩn OpenAI nên thư viện OpenAI chính thức hoạt động ngay sau khi đổi baseURL.

Tình trạng hiện tại

Để bạn không mất thời gian tìm kiếm một gói không tồn tại, chúng tôi công bố rõ phạm vi hiện có:

  • Chưa có gói npm hoặc PyPI mang thương hiệu Chat Tự Động. Nếu phát hiện gói trùng tên trên registry công khai, đó không phải sản phẩm của chúng tôi và không nên cài đặt.
  • Đã có đặc tả OpenAPI sinh trực tiếp từ mã nguồn tại https://api.chattudong.com/docs, dùng để tự sinh client cho ngôn ngữ bạn cần.
  • Đã có khả năng tương thích OpenAI tại /v1/models và /v1/chat/completions, đáp ứng phần lớn nhu cầu tích hợp.

Cách tiếp cận này mang lại một lợi ích thiết thực: doanh nghiệp không bị ràng buộc vào nhà cung cấp. Mã nguồn viết cho hệ thống của chúng tôi chỉ cần đổi baseURL là hoạt động với OpenAI hoặc bất kỳ nhà cung cấp tương thích nào khác mà không phải viết lại.

Node.js / TypeScript

Cài đặt thư viện chính thức của OpenAI rồi trỏ baseURL sang https://api.chattudong.com/v1. Giá trị truyền vào apiKey là API key của Chat Tự Động, bắt đầu bằng ck_live_, không phải khoá của OpenAI.

Cài đặt
npm install openai
Gọi model và nhận trả lời đầy đủ
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.chattudong.com/v1",
  apiKey: process.env.CHATLY_API_KEY,   // ck_live_…
});

const res = await client.chat.completions.create({
  model: "local/gemma-3-12b",
  messages: [
    { role: "system", content: "Bạn là trợ lý của một cửa hàng thời trang. Trả lời ngắn gọn." },
    { role: "user", content: "Cửa hàng mở cửa lúc mấy giờ?" },
  ],
  temperature: 0.3,
  max_tokens: 512,
});

console.log(res.choices[0]?.message.content);

Streaming

Hiển thị câu trả lời theo luồng
const stream = await client.chat.completions.create({
  model: "local/gemma-3-12b",
  messages: [{ role: "user", content: "Tư vấn giúp tôi chọn size áo" }],
  stream: true,
});

for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content;
  if (delta) process.stdout.write(delta);
}

Đọc chi phí đã phát sinh

Phản hồi có thêm khối chatly nằm ngoài chuẩn OpenAI nên định nghĩa kiểu của thư viện không bao gồm trường này. Chỉ cần ép kiểu một lần là truy cập được:

TypeScript
type UsageMeta = { charged_micros: string; byok: boolean };

const meta = (res as unknown as { chatly?: UsageMeta }).chatly;
if (meta) {
  console.log("Đã trừ (micro):", meta.charged_micros, "| BYOK:", meta.byok);
}

Python

Cài đặt
pip install openai
Gọi model
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.chattudong.com/v1",
    api_key=os.environ["CHATLY_API_KEY"],   # ck_live_…
)

res = client.chat.completions.create(
    model="local/gemma-3-12b",
    messages=[
        {"role": "system", "content": "Bạn là trợ lý của một cửa hàng thời trang. Trả lời ngắn gọn."},
        {"role": "user", "content": "Cửa hàng mở cửa lúc mấy giờ?"},
    ],
    temperature=0.3,
    max_tokens=512,
)

print(res.choices[0].message.content)
Streaming
stream = client.chat.completions.create(
    model="local/gemma-3-12b",
    messages=[{"role": "user", "content": "Tư vấn giúp tôi chọn size áo"}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)
Liệt kê model đang khả dụng
for m in client.models.list().data:
    print(m.id)

cURL và các ngôn ngữ khác

Nếu chưa có thư viện phù hợp, việc gọi trực tiếp qua HTTP cũng chỉ là một request JSON, triển khai được bằng vài dòng mã trong bất kỳ ngôn ngữ nào.

Terminal
curl https://api.chattudong.com/v1/chat/completions \
  -H "Authorization: Bearer $CHATLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "local/gemma-3-12b",
    "messages": [{"role": "user", "content": "Cửa hàng mở cửa lúc mấy giờ?"}]
  }'

Để sinh client tự động cho Go, Java, C# hoặc PHP, sử dụng đặc tả OpenAPI tại https://api.chattudong.com/docs với công cụ sinh mã phù hợp. Đặc tả này được sinh trực tiếp từ mã nguồn nên luôn khớp với API thực tế.

Các điểm khác biệt so với OpenAI

Tương thích không đồng nghĩa với giống hệt. Dưới đây là những khác biệt cần nắm trước khi chuyển mã nguồn sẵn có sang:

  • Quy ước đặt tên model khác. Id model có dạng provider/model, ví dụ local/gemma-3-12b. Không nên phỏng đoán, hãy gọi GET /v1/models để lấy danh sách đang kích hoạt cho tổ chức của bạn.
  • Phản hồi có thêm khối chatly gồm charged_micros và byok. Thư viện OpenAI bỏ qua các trường không nhận diện được nên không phát sinh lỗi.
  • Bộ mã lỗi riêng. Thân phản hồi lỗi có dạng { error: { code, message, requestId } } với bộ mã riêng, xem chi tiết tại bảng mã lỗi. Nếu mã nguồn hiện tại xử lý lỗi theo bộ mã của OpenAI, bạn cần điều chỉnh phần này.
  • Có header mở rộng riêng. x-chatly-use-byok: true để sử dụng khoá provider của doanh nghiệp, xem chi tiết tại hướng dẫn BYOK.
  • Chưa hỗ trợ function calling, tool use, đầu vào hình ảnh, embeddings và tạo hình ảnh qua endpoint tương thích. Body chỉ nhận content ở dạng chuỗi. Với các nhu cầu này, doanh nghiệp nên gọi trực tiếp tới nhà cung cấp model.

Kế hoạch phát hành SDK riêng

Chúng tôi chỉ phát triển SDK riêng khi nó giải quyết được những nhu cầu mà thư viện OpenAI không đáp ứng, chẳng hạn thao tác với kho tri thức, quản lý kênh và truy xuất hội thoại. Với phần gọi model, việc xây dựng thêm một thư viện là không cần thiết.

Nếu doanh nghiệp cần client cho một ngôn ngữ cụ thể hoặc đã tự phát triển và muốn chia sẻ, vui lòng liên hệ chattudongcskh@gmail.com. Nhu cầu thực tế từ khách hàng là cơ sở tốt nhất để chúng tôi xác định thứ tự ưu tiên.