> 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/zh/si-you-ai/open-ai-router.md).

# VergeOS OpenAI 兼容 API

## 概述

VergeOS 提供一个兼容 OpenAI 的 API 端点，使应用程序能够使用标准 OpenAI API 格式与本地托管的大语言模型（LLM）交互。这让你可以在完全运行于 VergeOS 环境中的同时，使用熟悉的工具和库。

该 API 会自动将请求路由到你配置的助手及其底层模型，为 AI 交互提供统一接口。

## 前提条件

在使用兼容 OpenAI 的 API 之前，请确保以下组件正在运行：

1. **AI-Helper Worker**：此 worker 负责处理 API 请求，且必须正在运行。当启用 AI 服务时，它会自动启动。
2. **至少有一个带有 Online 模型的助手**：必须已配置一个助手，并且其底层模型必须处于“Online”状态。

要验证这些前提条件：

1. 导航到 **AI → 查看 Workers** 以确认 AI-Helper Worker 正在运行
2. 导航到 **AI → 助手** 以确认至少有一个助手显示“Online”状态

## API 端点

兼容 OpenAI 的 API 可在以下地址使用：

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

### 支持的端点

| 端点                     | 描述               |
| ---------------------- | ---------------- |
| `/v1/models`           | 列出可用模型（返回已配置的助手） |
| `/v1/chat/completions` | 生成聊天补全           |

## 身份验证

API 请求需要使用 Bearer 令牌进行身份验证：

```
Authorization: Bearer <your-api-key>
```

### 创建 API 密钥

1. 导航到 **系统 → 用户**
2. 选择将拥有该 API 密钥的用户（或创建一个新用户）
3. 点击 **新建 API 密钥** 在左侧菜单中
4. 配置密钥设置：
   * **名称**：密钥的描述性名称（例如， `my-app-key`)
   * **描述** （可选）：关于密钥用途的附加详情
   * **过期类型**：选择“设置日期”或“永不过期”
   * **到期时间**：如果使用“设置日期”，请选择到期日期/时间
5. 保存密钥并复制生成的令牌

{% hint style="warning" %}
**安全性**

API 密钥在创建时只会显示一次。请安全保存，因为之后无法再次检索。
{% endhint %}

API 密钥继承其关联用户的权限。用于生产环境时，建议创建一个具有适当权限的专用 API 用户。

## 基本用法

### 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",  # 使用助手名称
    messages=[
        {"role": "user", "content": "用 Python 编写一个 hello world 函数"}
    ],
    max_tokens=1024,
    temperature=0.7
)

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

### 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": "你好！"}],
    "max_tokens": 100
  }'
```

### 列出可用模型

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

{% hint style="info" %}
**模型名称**

在 API 请求中，请使用 **助手名称** （例如， `qwen3-coder-14B`）作为 `model` 参数，而不是底层模型名称（例如， `Qwen3-14B-Q6_K`).
{% endhint %}

## 响应格式

响应遵循标准 OpenAI 格式，并附加了时间信息：

```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": "此处为响应内容"
      }
    }
  ],
  "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
  }
}
```

该 `timings` 字段提供标准 OpenAI API 中没有的性能指标。

## 配置助手

助手定义 API 如何与底层模型交互。该助手 **名称** 用于 `model` API 请求中的参数。

有关创建和配置助手的详细说明，请参阅 [AI 配置指南](/automate-protect-and-extend/zh/si-you-ai/configuration.md#ai-assistant-management).

{% hint style="success" %}
**API 使用的关键设置**

* **名称**：这将成为 `model` API 调用中的参数
* **Disable think**：对于具有思考能力的模型，启用此项可通过 API 返回内容
* **系统提示词**：自动应用于每个 API 请求
  {% endhint %}

## Workers

AI 系统使用两类 worker：

* **AI-Helper Worker**：处理 API 请求并将其路由到模型。自动启动，并且 API 正常运行所必需。
* **模型 Worker**：处理每个正在运行模型的推理。当模型启动时自动创建。

在以下位置查看 worker 状态 **AI → 查看 Workers**.

## 多轮对话

API 通过包含消息历史来支持多轮对话：

```python
response = client.chat.completions.create(
    model="qwen3-coder-14B",
    messages=[
        {"role": "user", "content": "什么是 Python？"}，
        {"role": "assistant", "content": "Python 是一种编程语言..."}，
        {"role": "user", "content": "给我看一个简单示例"}
    ]
)
```

当 **聊天历史** 在助手上启用时，系统还可以在同一会话内的多次 API 调用之间维护上下文。

## 使用思考模型

某些模型（如 Qwen3）具有“思考”能力，它们会在响应前先在内部对问题进行推理。

如果你通过 API 使用此类模型并收到空响应，模型可能正在输出被从响应中过滤掉的思考 tokens。要获取实际响应内容：

1. 导航到 **AI → 助手**
2. 点击你的助手
3. 点击 **编辑助手**
4. 启用 **Disable think** 切换开关
5. 点击 **提交**

这会抑制思考过程，只返回最终响应。

## 集成示例

### IDE 集成

许多 IDE 支持自定义兼容 OpenAI 的端点。请按以下方式配置你的 IDE：

* **API 基础 URL**: `https://your-vergeos-instance.com/v1`
* **API 密钥**：你的 VergeOS API 密钥
* **模型**：你的助手名称（例如， `qwen3-coder-14B`)

### 应用程序集成

使用任意 OpenAI 客户端库：

{% 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 %}

## 故障排除

### 需要登录错误

```json
{"err":"需要登录"}
```

**原因**：缺少或无效的 API 密钥。

**解决方案**：在 Authorization 标头中包含有效的 API 密钥。

### 空响应内容

**原因**：模型正在使用被输出过滤掉的思考 tokens。

**解决方案**：在助手设置中启用“Disable think”。

### 未找到模型

**原因**：指定的模型名称与任何助手都不匹配。

**解决方案**:

* 使用准确的助手名称（区分大小写）
* 在以下位置验证助手是否存在 **AI → 助手**
* 确保助手的模型处于 Online 状态

### 连接被拒绝

**原因**：AI-Helper Worker 未运行。

**解决方案**:

* 检查 **AI → 查看 Workers** 以验证 AI-Helper Worker 状态
* 必要时重启 AI 服务

### 响应缓慢

**原因**：模型正在加载或负载过高。

**解决方案**:

* 在以下位置检查 worker 资源使用情况 **AI → 查看 Workers**
* 考虑为该模型分配更多 CPU 核心或内存
* 使用更小的模型以获得更快响应

***

**版本兼容性**：此功能适用于 VergeOS 26.0 及更高版本。


---

# 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/zh/si-you-ai/open-ai-router.md?ask=<question>&goal=<endgoal>
```

`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.