Ai00 API 文档

本页介绍 Ai00 Server v0.7.1 当前提供的推理与管理接口。如果你第一次调用 Ai00，可以先完成下面的最小聊天请求；需要查找字段时，再展开对应接口的请求主体和响应结构。

• 默认地址：http://localhost:65530
• Swagger UI：http://localhost:65530/api-docs
• OpenAPI JSON：http://localhost:65530/api-docs/openapi.json
• 上游路由源码：crates/ai00-server/src/api

发送第一个聊天请求

开始之前，请先按照 Ai00 轻松使用 启动服务并加载一个 RWKV 模型。可以先查询当前模型：

curl http://localhost:65530/api/oai/v1/models

如果响应的 data 中出现模型名称，说明服务和模型已经准备完成。接着发送一条最小聊天请求：

curl http://localhost:65530/api/oai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "请用一句话介绍 RWKV" }
    ],
    "max_tokens": 128,
    "stream": false
  }'

$body = @{
  messages = @(
    @{ role = "user"; content = "请用一句话介绍 RWKV" }
  )
  max_tokens = 128
  stream = $false
} | ConvertTo-Json -Depth 4

Invoke-RestMethod `
  -Uri "http://localhost:65530/api/oai/v1/chat/completions" `
  -Method Post `
  -ContentType "application/json" `
  -Body $body

成功响应的 choices[0].message.content 是模型生成的回答。如果请求无法连接，请先确认 Ai00 的监听地址、端口和 TLS 配置；如果接口可以访问但不能生成，请检查模型是否已经加载，以及终端中是否出现显存或模型格式错误。

上面的请求只使用了最必要的字段。names、template、采样器和 State 等配置可以在确认基础调用成功后逐步添加。

按任务选择接口

大多数应用只会使用聊天补全或文本续写。State、候选排序和管理接口用于更具体的集成场景，不需要在第一次调用时全部实现。

OpenAI 风格与推理接口

/api/oai/v1/embeds 使用独立的文本 Embedding 模型，并不是从当前加载的 RWKV 模型中提取向量。只需要聊天或续写时，可以忽略这个接口。

运行时与管理接口

聊天补全

聊天补全适合多轮对话，也是普通应用最常用的接口。每次请求应把当前对话所需的消息放入 messages；Ai00 会按照 template 将它们拼接后交给 RWKV 模型。

文本续写

文本续写直接接在 prompt 后生成内容，不会自动组织 system、user、assistant 等聊天角色。它适合补全文本、批量续写，或由你的应用自行拼接提示词的场景。

候选排序

如果你的应用已经准备了多个候选答案，可以使用这个接口计算每个候选项的困惑度，并让 Ai00 按匹配程度排序。困惑度越低，表示候选文本越符合当前模型对输入内容的预测。

生成 State

RWKV State 可以理解为模型阅读一段文本后的内部状态。这个接口适合预先处理固定背景、角色设定或较长的公共前缀，再在后续请求中复用结果。返回的 State 数据可能很大，请不要把完整响应直接写入普通业务日志。

外部 Embedding 模型

这个接口不使用当前加载的 RWKV 模型。只有在 Ai00 构建时启用了 embed feature，并且另外加载了文本 Embedding 模型时，路由才可用。

模型信息

在发送生成请求前，可以先调用这个接口确认 Ai00 当前加载的是哪个模型。它也适合作为应用启动时的简单连通性检查。

采样器格式

普通调用可以直接使用请求顶层的 top_p、top_k 和 temperature。只有需要完整控制采样方法时，才传入 sampler 对象；一旦提供 sampler，其中的配置会覆盖顶层采样参数。

Nucleus

{
  "type": "Nucleus",
  "top_p": 0.5,
  "top_k": 128,
  "temperature": 1,
  "presence_penalty": 0.3,
  "frequency_penalty": 0.3,
  "penalty_decay": 0.99654026
}

Mirostat

{
  "type": "Mirostat",
  "tau": 3,
  "rate": 0.1
}

Typical

{
  "type": "Typical",
  "tau": 0.5,
  "top_k": 128,
  "temperature": 1,
  "presence_penalty": 0.3,
  "frequency_penalty": 0.3,
  "penalty_decay": 0.99654026
}

管理员鉴权

推理接口用于生成内容，管理接口则可以加载模型、修改配置或操作服务器文件。两类接口应使用不同的访问控制策略。

先在 Config.toml 中配置管理应用的 app_id 和 app_secret，再调用下面的接口换取 JWT。不要把 app_secret 写入浏览器端代码或公开仓库。

换取令牌后，推荐通过 Authorization: Bearer <token> 请求头调用管理接口。查询参数 admin_token=<token> 也能提交令牌，但它更容易出现在代理和访问日志中，不建议在生产环境使用。

加载模型、LoRA 与 State

这个管理接口会销毁当前运行时，并按照请求内容重新加载模型。第一次调试时建议只填写 model_path 和必要的精度参数；确认模型能够加载后，再逐步加入 LoRA、State 和量化设置。

其他管理端点

下面列出 WebUI 和自动化部署可能使用的管理接口。普通聊天客户端不需要调用这些端点。

响应与类型约定

下面这些规则在多个接口中重复出现。开发客户端时可以集中实现，避免为每个端点编写不同的解析逻辑：

• Ai00 的 token 统计字段是 prompt、completion、total。
• finish_reason 可能是 stop、length、content_filter 或 null。
• stop、prompt、input 使用 Ai00 的 Array<T> 类型，通常同时接受单值和数组。
• state 可以是 UUID，也可以传完整 State 数据或 State 文件描述对象。
• 流式聊天使用 chat.completion.chunk；流式续写使用 text_completion.chunk。

历史与兼容接口

兼容路径

已移除接口

兼容请求字段