VergeOS 兼容 OpenAI 的 API

VergeOS 兼容 OpenAI 的 API 端点文档，使应用程序可使用标准 OpenAI API 格式，并通过 Python、JavaScript 和 cURL 与本地托管的 LLM 交互。

概述

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. 保存密钥并复制生成的令牌

安全性

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

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

基本用法

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 示例

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
  }'

列出可用模型

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

模型名称

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

响应格式

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

{
  "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 配置指南.

API 使用的关键设置

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

Workers

AI 系统使用两类 worker：

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

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

多轮对话

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

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 客户端库：

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": [...]}'

故障排除

需要登录错误

{"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 及更高版本。