API tương thích OpenAI của VergeOS

Tài liệu cho điểm cuối API tương thích OpenAI của VergeOS, cho phép ứng dụng tương tác với các LLM được lưu trữ cục bộ bằng định dạng API OpenAI tiêu chuẩn với Python, JavaScript và cURL.

Tổng quan

VergeOS cung cấp một điểm cuối API tương thích OpenAI cho phép các ứng dụng tương tác với các mô hình ngôn ngữ lớn (LLM) được lưu trữ cục bộ bằng định dạng API OpenAI tiêu chuẩn. Điều này cho phép bạn sử dụng các công cụ và thư viện quen thuộc trong khi chạy các mô hình hoàn toàn trong môi trường VergeOS của bạn.

API tự động định tuyến các yêu cầu đến các trợ lý đã cấu hình và các mô hình nền tảng của chúng, cung cấp một giao diện thống nhất cho các tương tác AI.

Điều kiện tiên quyết

Trước khi sử dụng API tương thích OpenAI, hãy đảm bảo các thành phần sau đang chạy:

1. AI-Helper Worker: Worker này xử lý các yêu cầu API và phải đang chạy. Nó tự động khởi động khi dịch vụ AI được bật.
2. Ít nhất một trợ lý với mô hình Online: Một trợ lý phải được cấu hình và mô hình nền tảng của nó phải ở trạng thái "Online".

Để xác minh các điều kiện tiên quyết này:

1. Đi tới AI → View Workers để xác nhận AI-Helper Worker đang chạy
2. Đi tới AI → Assistants để xác nhận ít nhất một trợ lý hiển thị trạng thái "Online"

Các điểm cuối API

API tương thích OpenAI có sẵn tại:

https://<your-vergeos-url>/v1

Các điểm cuối được hỗ trợ

Điểm cuối	Mô tả
/v1/models	Liệt kê các mô hình khả dụng (trả về các trợ lý đã cấu hình)
/v1/chat/completions	Tạo các phản hồi hoàn thành hội thoại

Xác thực

Các yêu cầu API cần xác thực bằng mã Bearer:

Authorization: Bearer <your-api-key>

Tạo khóa API

1. Đi tới System → Users
2. Chọn người dùng sẽ sở hữu khóa API (hoặc tạo người dùng mới)
3. Nhấp Khóa API mới trong menu bên trái
4. Cấu hình các cài đặt của khóa:

   • Tên: Một tên mô tả cho khóa (ví dụ, my-app-key)
   • Mô tả (tùy chọn): Thêm chi tiết về mục đích của khóa
   • Loại hết hạn: Chọn "Set Date" hoặc "Never"
   • Hết hạn: Nếu dùng Set Date, hãy chọn ngày/giờ hết hạn
5. Lưu khóa và sao chép mã token được tạo

Bảo mật

Khóa API chỉ được hiển thị một lần khi tạo. Hãy lưu trữ nó an toàn vì sau này không thể truy xuất lại.

Khóa API kế thừa quyền của người dùng liên kết với chúng. Khi dùng cho môi trường production, hãy cân nhắc tạo một người dùng API chuyên dụng với các quyền phù hợp.

Cách sử dụng cơ bản

Ví dụ Python

from openai import OpenAI

client = OpenAI(
    base_url="https://your-vergeos-instance.com/v1",
    api_key="your-api-key"
)

response = client.chat.completions.create(
    model="qwen3-coder-14B",  # Sử dụng tên trợ lý
    messages=[
        {"role": "user", "content": "Write a hello world function in Python"}
    ],
    max_tokens=1024,
    temperature=0.7
)

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

Ví dụ cURL

curl https://your-vergeos-instance.com/v1/chat/completions \\
  -H "Authorization: Bearer your-api-key" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "qwen3-coder-14B",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 100
  }'

Liệt kê các mô hình khả dụng

curl https://your-vergeos-instance.com/v1/models \\
  -H "Authorization: Bearer your-api-key"

Tên mô hình

Trong các yêu cầu API, hãy dùng tên trợ lý (ví dụ, qwen3-coder-14B) làm tham số model, không phải tên mô hình nền tảng (ví dụ, Qwen3-14B-Q6_K).

Định dạng phản hồi

Các phản hồi tuân theo định dạng OpenAI tiêu chuẩn với thông tin thời gian bổ sung:

{
  "id": "unique-completion-id",
  "object": "chat.completion",
  "created": 1768822431,
  "model": "assistant-name",
  "system_fingerprint": "assistant-name",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Nội dung phản hồi ở đây"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 100,
    "total_tokens": 132
  },
  "timings": {
    "prompt_n": 12,
    "prompt_ms": 365.388,
    "prompt_per_token_ms": 30.449,
    "prompt_per_second": 32.84,
    "predicted_n": 100,
    "predicted_ms": 1620.788,
    "predicted_per_token_ms": 16.21,
    "predicted_per_second": 61.70
  }
}

Danh sách timings trường này cung cấp các chỉ số hiệu năng không có trong API OpenAI tiêu chuẩn.

Cấu hình trợ lý

Các trợ lý xác định cách API tương tác với các mô hình nền tảng. Trợ lý Tên được dùng làm tham số tham số trong các yêu cầu API.

Để biết hướng dẫn chi tiết về cách tạo và cấu hình trợ lý, hãy xem Hướng dẫn cấu hình AI.

Cài đặt chính để sử dụng API

• Tên: Đây sẽ trở thành tham số tham số trong các lệnh gọi API
• Tắt suy luận: Bật tính năng này cho các mô hình có khả năng suy luận để trả nội dung qua API
• Prompt hệ thống: Được áp dụng tự động cho mọi yêu cầu API

Worker

Hệ thống AI sử dụng hai loại worker:

• AI-Helper Worker: Xử lý các yêu cầu API và định tuyến chúng đến các mô hình. Tự động khởi động và bắt buộc để API hoạt động.
• Worker mô hình: Xử lý suy luận cho từng mô hình đang chạy. Được tạo tự động khi một mô hình khởi động.

Xem trạng thái worker tại AI → View Workers.

Hội thoại nhiều lượt

API hỗ trợ hội thoại nhiều lượt bằng cách bao gồm lịch sử tin nhắn:

response = client.chat.completions.create(
    model="qwen3-coder-14B",
    messages=[
        {"role": "user", "content": "What is Python?"},
        {"role": "assistant", "content": "Python là một ngôn ngữ lập trình..."},
        {"role": "user", "content": "Show me a simple example"}
    ]
)

Khi Lịch sử chat được bật trên trợ lý, hệ thống cũng có thể duy trì ngữ cảnh qua các lệnh gọi API riêng biệt trong một phiên.

Làm việc với các mô hình có khả năng suy luận

Một số mô hình (như Qwen3) có khả năng "suy luận" khi chúng tự phân tích vấn đề bên trong trước khi trả lời.

Nếu bạn đang dùng mô hình như vậy qua API và nhận được phản hồi trống, có thể mô hình đang xuất các token suy nghĩ bị lọc khỏi phản hồi. Để lấy nội dung phản hồi thực tế:

1. Đi tới AI → Assistants
2. Nhấp vào trợ lý của bạn
3. Nhấp Chỉnh sửa trợ lý
4. Bật Tắt suy luận công tắc
5. Nhấp Gửi

Điều này sẽ ẩn quá trình suy nghĩ và chỉ trả về phản hồi cuối cùng.

Ví dụ tích hợp

Tích hợp IDE

Nhiều IDE hỗ trợ các điểm cuối tương thích OpenAI tùy chỉnh. Hãy cấu hình IDE của bạn với:

• URL cơ sở API: https://your-vergeos-instance.com/v1
• Khóa API: Khóa API VergeOS của bạn
• Mô hình: Tên trợ lý của bạn (ví dụ, qwen3-coder-14B)

Tích hợp ứng dụng

Sử dụng bất kỳ thư viện client OpenAI nào:

Python

from openai import OpenAI
client = OpenAI(base_url="https://your-vergeos-instance.com/v1", api_key="your-key")

JavaScript

import OpenAI from 'openai';
const client = new OpenAI({
  baseURL: 'https://your-vergeos-instance.com/v1',
  apiKey: 'your-key'
});

cURL

curl https://your-vergeos-instance.com/v1/chat/completions \\
  -H "Authorization: Bearer your-key" \\
  -H "Content-Type: application/json" \\
  -d '{"model": "assistant-name", "messages": [...]}'

Khắc phục sự cố

Lỗi yêu cầu đăng nhập

{"err":"Login required"}

Nguyên nhân: Thiếu hoặc khóa API không hợp lệ.

Giải pháp: Bao gồm một khóa API hợp lệ trong header Authorization.

Nội dung phản hồi trống

Nguyên nhân: Mô hình đang sử dụng các token suy nghĩ bị lọc khỏi đầu ra.

Giải pháp: Bật "Tắt suy luận" trong cài đặt trợ lý.

Không tìm thấy mô hình

Nguyên nhân: Tên mô hình được chỉ định không khớp với bất kỳ trợ lý nào.

Giải pháp:

• Sử dụng đúng tên trợ lý (phân biệt chữ hoa chữ thường)
• Xác minh trợ lý tồn tại tại AI → Assistants
• Đảm bảo mô hình của trợ lý ở trạng thái Online

Kết nối bị từ chối

Nguyên nhân: AI-Helper Worker không đang chạy.

Giải pháp:

• Kiểm tra AI → View Workers để xác minh trạng thái AI-Helper Worker
• Khởi động lại dịch vụ AI nếu cần

Phản hồi chậm

Nguyên nhân: Mô hình đang tải hoặc đang chịu tải cao.

Giải pháp:

• Kiểm tra mức sử dụng tài nguyên của worker tại AI → View Workers
• Cân nhắc phân bổ thêm lõi CPU hoặc RAM cho mô hình
• Sử dụng mô hình nhỏ hơn để phản hồi nhanh hơn

---

Tương thích phiên bản: Chức năng này có sẵn trong VergeOS 26.0 trở lên.