> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/automate-protect-and-extend/vi/ai-rieng-tu/open-ai-router.md). # API tương thích OpenAI của VergeOS ## 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:///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 ``` ### 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 {% hint style="warning" %} **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. {% endhint %} 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 ```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 ```bash 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 ```bash curl https://your-vergeos-instance.com/v1/models \\ -H "Authorization: Bearer your-api-key" ``` {% hint style="info" %} **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`). {% endhint %} ## Đị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: ```json { "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](/automate-protect-and-extend/vi/ai-rieng-tu/configuration.md#ai-assistant-management). {% hint style="success" %} **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 {% endhint %} ## 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: ```python 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: {% tabs %} {% tab title="Python" %} ```python from openai import OpenAI client = OpenAI(base_url="https://your-vergeos-instance.com/v1", api_key="your-key") ``` {% endtab %} {% tab title="JavaScript" %} ```javascript import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'https://your-vergeos-instance.com/v1', apiKey: 'your-key' }); ``` {% endtab %} {% tab title="cURL" %} ```bash curl https://your-vergeos-instance.com/v1/chat/completions \\ -H "Authorization: Bearer your-key" \\ -H "Content-Type: application/json" \\ -d '{"model": "assistant-name", "messages": [...]}' ``` {% endtab %} {% endtabs %} ## Khắc phục sự cố ### Lỗi yêu cầu đăng nhập ```json {"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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.verge.io/automate-protect-and-extend/vi/ai-rieng-tu/open-ai-router.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.