Ai00 的 API 文档
以下是 Ai00 的 API 文档,包含所有 API 的详细说明。
本地启动 Ai00 后,可以通过 http://localhost:65530/api-docs/
打开 Ai00 的 API 文档。
api/oai/chat/completions
API 功能:api/oai/chat/completions
和 api/oai/v1/chat/completions
是相同的 API ,用于 RWKV 的聊天续写模式,也就是和模型对话。
API 地址:(post)http://localhost:65530/api/oai/chat/completions
参数列表:
参数名称 | 是否可选 | 类型 | 参数解释 |
---|---|---|---|
messages | 必选 | array<object> | 对话历史记录,每个对象包含 role(角色)和 content(内容)两个字段 |
names | 必选 | object<Role, string> | 角色名称映射,可以自定义 system/user/assistant/observation 等角色的显示名 |
state | 可选 | string | 指定使用的 RWKV state 文件 UUID |
max_tokens | 可选 | integer | 生成文本的最大 token 数 |
stop | 可选 | array<string> | 停止词列表,当生成内容包含这些词时会停止生成,默认值为 ["\n\n"] |
stream | 可选 | boolean | 是否以流模式生成文本,默认值为 false |
bias | 可选 | object<number, number> | token id 到权重的映射,用于调整特定 token 的生成概率,默认为空 |
bnf_schema | 可选 | string | null | BNF 语法规则,用于约束模型输出格式,默认为 null |
sampler | 可选 | object | 默认的采样参数(Nucleus 类型) |
sampler_override | 可选 | Option<SamplerParams> | 覆盖默认采样参数,可以选择不同的采样方法 |
参考的 API 请求主体
{
"max_tokens": 1000,
"messages": [
{
"content": "Hi!",
"role": "user"
},
{
"content": "Hello, I am your AI assistant. If you have any questions or instructions, please let me know!",
"role": "assistant"
},
{
"content": "Tell me about water.",
"role": "user"
}
],
"names": {
"assistant": "Assistant",
"user": "User"
},
"sampler_override": {
"frequency_penalty": 0.3,
"penalty": 400,
"penalty_decay": 0.99654026,
"presence_penalty": 0.3,
"temperature": 1,
"top_k": 128,
"top_p": 0.5,
"type": "Nucleus"
},
"state": "00000000-0000-0000-0000-000000000000",
"stop": [
"\n\nUser:"
],
"stream": false
}
参考的 API 返回结果
{
"object": "chat.completion",
"model": "assets/models\\RWKV-x060-World-1B6-v2.1-20240328-ctx4096.st",
"choices": [
{
"message": {
"role": "Assistant",
"content": "Water is a liquid that is essential for life on Earth. It is a mixture of hydrogen and oxygen atoms, which makes it a highly reactive and polar molecule. Water has a high surface tension and is able to form water droplets when it comes into contact with other substances. It is found in various forms, including ice, snow, rain, and fog. Water is also essential for the growth and survival of plants and animals."
},
"index": 0,
"finish_reason": "stop"
}
],
"usage": {
"prompt": 41,
"completion": 88,
"total": 129,
"duration": {
"secs": 4,
"nanos": 381959200
}
}
}
返回结果说明:
object
: 返回对象类型,固定为 "chat.completion"model
: 当前使用的模型路径choices
: 生成结果数组,包含以下字段:message
: 生成的消息对象,包含:role
: 角色类型,固定为 "Assistant"content
: 生成的文本内容
index
: 结果的索引号finish_reason
: 生成停止的原因
usage
: 使用统计信息,包含以下字段:prompt
: 输入提示的 token 数量completion
: 生成内容的 token 数量total
: 总 token 数量duration
: 生成耗时,包含秒和纳秒
api/oai/completions
API 功能:api/oai/completions
和 api/oai/v1/completions
是相同的续写 API,用于基础续写模式,让模型接着你的 prompt 继续生成内容。
API 地址:(post)http://localhost:65530/api/oai/completions
参数列表:
参数名称 | 是否可选 | 类型 | 参数解释 |
---|---|---|---|
prompt | 必选 | Array<String> | 你提供给模型的续写提示文本数组 |
state | 可选 | string | 指定使用的 RWKV state 文件 UUID |
max_tokens | 可选 | integer | 生成文本的最大 token 数,默认值为 256 |
stop | 可选 | Array<String> | 停止词列表,当生成内容包含这些词时会停止生成,默认值为 ["\n\n"] |
stream | 可选 | boolean | 是否以流模式生成文本,默认值为 false |
bias | 可选 | HashMap<u16, f32> | token id 到权重的映射,用于调整特定 token 的生成概率,默认为空 |
bnf_schema | 可选 | Option<String> | BNF 语法规则,用于约束模型输出格式,默认为 None |
sampler | 可选 | NucleusParams | 默认的 Nucleus 采样参数 |
sampler_override | 可选 | Option<SamplerParams> | 覆盖默认采样参数,可以选择不同的采样方法 |
参考的请求主体:
{
"prompt": [
"The Eiffel Tower is located in the city of"
],
"stop": [
"\n\n",
"."
],
"stream": false,
"max_tokens": 1000,
"sampler_override": {
"type": "Nucleus",
"top_p": 0.5,
"top_k": 128,
"temperature": 1,
"presence_penalty": 0.3,
"frequency_penalty": 0.3,
"penalty": 400,
"penalty_decay": 0.99654026
},
"state": "00000000-0000-0000-0000-000000000000"
}
参考的 API 返回结果
{
"object": "text_completion",
"model": "assets/models\\RWKV-x060-World-3B-v2.1-20240417-ctx4096.st",
"choices": [
{
"text": " Paris, France",
"index": 0,
"finish_reason": "stop"
}
],
"usage": {
"prompt": 11,
"completion": 4,
"total": 15,
"duration": {
"secs": 0,
"nanos": 260801800
}
}
}
返回结果说明:
object
: 返回对象类型,固定为 "text_completion"model
: 当前使用的模型路径choices
: 生成结果数组,包含以下字段:text
: 生成的文本内容index
: 结果的索引号finish_reason
: 生成停止的原因
usage
: 使用统计信息,包含以下字段:prompt
: 输入提示的 token 数量completion
: 生成内容的 token 数量total
: 总 token 数量duration
: 生成耗时,包含秒和纳秒
api/oai/chooses
API 功能:API 拥有 "input" 和 "choices" 参数,即给定输入和选项,让模型按照困惑度对选项进行排名,从而选出最合适的回答。
api/oai/chooses
和 api/oai/v1/chooses
是相同的 API。
API 地址:(post)http://localhost:65530/api/oai/chooses
参数列表:
参数名称 | 是否可选 | 类型 | 参数解释 |
---|---|---|---|
input | 必选 | Array<String> | 提供给模型的输入文本数组 |
choices | 必选 | Array<String> | 供模型选择的选项数组 |
state | 可选 | string | 指定使用的 RWKV state 文件 UUID |
参考的 API 请求主体
{
"choices": [
" Paris",
" Seattle",
" San Francisco",
" Shanghai"
],
"input": [
"The Eiffel Tower is located in the city of"
],
"state": "00000000-0000-0000-0000-000000000000"
}
参考的 API 返回结果
{
"object": "list",
"model": "assets/models\\RWKV-x060-World-3B-v2.1-20240417-ctx4096.st",
"data": [
{
"object": "choice",
"index": 0,
"rank": 0,
"choice": " Paris",
"perplexity": 0.031040953
},
{
"object": "choice",
"index": 2,
"rank": 1,
"choice": " San Francisco",
"perplexity": 6.299065
},
{
"object": "choice",
"index": 3,
"rank": 2,
"choice": " Shanghai",
"perplexity": 12.735298
},
{
"object": "choice",
"index": 1,
"rank": 3,
"choice": " Seattle",
"perplexity": 14.686427
}
]
}
返回结果说明:
object
: 返回对象类型,固定为 "list"model
: 当前使用的模型路径data
: 选择结果数组,包含以下字段:object
: 选项类型,固定为 "choice"index
: 选项在原始 choices 数组中的索引rank
: 选项在排序后的排名(0 为最佳选择)choice
: 选项内容perplexity
: 困惑度分数,分数越低表示该选项越合适
api/oai/embeddings
API 功能:api/oai/embeddings
和 api/oai/v1/embeddings
是相同的 API,使用当前加载的 RWKV 模型为给定文本生成嵌入向量,可指定生成嵌入向量的模型层数。
API 地址:(post)http://localhost:65530/api/oai/embeddings
参数列表:
参数名称 | 是否可选 | 类型 | 参数解释 |
---|---|---|---|
input | 是 | ( null | string | array<string> ) | 给嵌入模型的文本 |
layer | 是 | integer | 指定生成嵌入向量的层数 |
state | 是 | string | 指定使用的 RWKV state 文件路径 |
参考的 API 请求主体
{
"input": "rwkv",
"layer": 0,
"state": "00000000-0000-0000-0000-000000000000"
}
参考的 API 返回结果
{
"object": "list",
"model": "assets/models\\RWKV-x060-World-1B6-v2.1-20240328-ctx4096.st",
"data": [
{
"object": "embedding",
"index": 0,
"embedding": "embedding": [0.37109375, -0.015655518, -0.01977539, /* ... */]
}
],
"usage": {
"prompt": 2,
"completion": 1,
"total": 3,
"duration": {
"secs": 0,
"nanos": 2200
}
}
}
返回结果说明:
object
: 返回对象类型,固定为 "list"model
: 当前使用的模型路径data
: 嵌入向量结果数组,包含以下字段:object
: 嵌入对象类型,固定为 "embedding"index
: 结果的索引号embedding
: 生成的嵌入向量数组,包含多个浮点数
usage
: 使用统计信息,包含以下字段:prompt
: 输入提示的 token 数量completion
: 生成内容的 token 数量total
: 总 token 数量duration
: 生成耗时,包含秒和纳秒
api/oai/embeds
API 功能:api/oai/embeds
和 api/oai/v1/embeds
是相同的 API,使用第三方模型为给定文本生成嵌入向量。
该 API 是调用第三方的嵌入模型来生成嵌入向量,使用 API 前需打开 \assets\configs\Config.toml
配置文件,将最底部五行配置代码取消注释:
[embed]
endpoint = "https://hf-mirror.com"
home = "assets/models/hf"
lib = "assets/ort/onnxruntime.dll"
name = { MultilingualE5Small = {} }
保存配置文件,重启 Ai00 即可自动下载第三方模型。终端的下载过程如图:
模型下载完成后,即可使用该 API 。
API 地址:(post)http://localhost:65530/api/oai/embeds
参数列表:
参数名称 | 是否可选 | 类型 | 参数解释 |
---|---|---|---|
input | 必选 | string | 需要生成嵌入向量的文本 |
max_tokens | 可选 | integer | 文本分块的最大 token 数,范围 1-510,默认值为 510 |
prefix | 可选 | string | 每个文本块的前缀,默认值为 "query:" |
参考的 API 请求主体
{
"input": "rwkv",
"max_tokens": 510,
"prefix": "query:"
}
参考的 API 返回结果
{
"object": "embeds",
"model": "intfloat/multilingual-e5-small",
"data": [
{
"object": "embed",
"index": 0,
"chunks": [
{
"chunk": "第一个文本块",
"embed": [
[0.37109375, -0.015655518, -0.01977539, /* ... */]
]
},
{
"chunk": "第二个文本块",
"embed": [
[0.20153809, 0.15637207, 0.24768066, /* ... */]
]
}
]
}
]
}
返回结果说明:
object
: 返回对象类型,固定为 "embeds"model
: 当前使用的嵌入模型data
: 嵌入向量结果数组,包含以下字段:object
: 嵌入对象类型,固定为 "embed"index
: 结果的索引号chunks
: 嵌入向量分块数组,包含以下字段:chunk
: 文本块内容embed
: 生成的嵌入向量数组,包含多个浮点数
api/oai/models
API 功能:api/oai/models
和 api/oai/v1/models
是相同的 API,用于获取当前加载的模型信息。
API 地址:(get)http://localhost:65530/api/oai/models
参考的 API 返回结果
{
"data": [
{
"object": "models",
"id": "RWKV-x060-World-1B6-v2.1-20240328-ctx4096"
}
]
}
返回结果说明:
data
: 模型结果数组,包含以下字段:object
: 模型对象类型,固定为 "models"id
: 模型的 id 名称
admin/models/load
API 功能:该 API 用于重新加载模型、 LoRA 、初始状态等运行时环境。
API 地址:(post)http://localhost:65530/admin/models/load
参数列表:
参数名称 | 是否可选 | 类型 | 参数解释 |
---|---|---|---|
adapter | 可选 | string | 指定使用的 GPU 和驱动后端,可使用 API api/adapters 查看,默认为 "Auto" |
bnf | 可选 | object | BNF 选项配置,用于配置 BNF 解析相关参数,默认为空 |
embed_device | 可选 | string | 在 GPU 还是 CPU 上放模型的 Embed 矩阵,默认为 "CPU" |
lora | 可选 | array | 是否加载 LoRA 文件,填 LoRA 文件的路径和 alpha 值等属性,默认为空 |
max_batch | 可选 | integer | 缓存在 GPU 上的最大批次,默认为 8 |
model_path | 必选 | string | 模型文件路径 |
precision | 可选 | string | 中间张量的精度,默认为 "Fp16" |
quant_type | 可选 | string | 量化类型 ("Int8" or "NF4"),Int8 效果比 NF4 好,但需要更多显存 |
quant | 可选 | integer | 量化层数,调高会提升效率,但可能损失精度使模型效果变差,默认为 0 |
state | 可选 | array | state 文件列表,每个元素包含 path 路径属性,默认为空 |
token_chunk_size | 可选 | integer | 一次并行处理的最大 token 数,默认为 128 |
tokenizer_path | 必选 | string | 指定使用的 RWKV 分词器路径 |
参考的 API 请求主体
{
"model_path": "RWKV-x060-ChnNovel-3B-20240807-ctx4096.st",
"adapter": {
"Manual": 0
},
"quant_type": "NF4",
"quant": 31,
"token_chunk_size": 128,
"max_batch": 16,
"tokenizer_path": "assets/tokenizer/rwkv_vocab_v20230424.json",
"embed_device": "Cpu",
"precision": "Fp16",
"lora": [
{
"alpha": 192,
"path": "test-x606-3B.lora"
}
],
"state": [
{
"path": "rwkv-x060-chn_single_round_qa-3B-20240516-ctx2048.state"
}
]
}
返回结果说明:
- 该 API 没有直接的返回值
- 响应状态码 200 表示请求成功
- 如果加载失败,会返回相应的错误状态码和错误信息
- 加载状态和进度可在部署 Ai00 服务的终端查看
admin/models/save
API 功能:该 API 能够以 .prefab
格式导出带有量化方法和量化层数两项配置的 RWKV 模型。
.prefab
预制件通常指游戏开发中使用的一种资源格式,允许开发者创建、保存和复用游戏对象(GameObject)及其组件的配置。
Ai00 支持导入和导出 .prefab
格式的 RWKV 模型,通过预量化 RWKV 模型节省加载时间。
API 地址:(post)http://localhost:65530/admin/models/save
参数列表:
参数名称 | 是否可选 | 类型 | 参数解释 |
---|---|---|---|
path | 必选 | string | 导出 .prefab RWKV 模型的路径 |
参考的 API 请求主体
{
"path": "/assets/models/temp.st"
}
返回结果说明:
- 该 API 没有直接的返回值`
- 响应状态码 200 表示请求成功
- 导出进度和结果可在部署服务的终端查看
- 导出成功后会在指定路径生成
.prefab
格式的模型文件
admin/models/state/load
API 功能:挂载指定路径的 state 文件。
作为 RNN 模型,RWKV 模型拥有固定大小的隐藏状态(State)。可通过加载 State 文件初始化 RWKV 模型的隐藏状态,以强化 RWKV 模型在特定任务的表现(类似于模型增强插件)。
API 地址:(post)http://localhost:65530/admin/models/state/load
参数列表:
参数名称 | 是否可选 | 类型 | 参数解释 |
---|---|---|---|
default | 可选 | boolean | 是否立即挂载此 state |
id | 可选 | string | state 文件的 UUID,不指定则随机分配 |
name | 可选 | string | null | 为 state 文件命名 |
path | 必选 | string | assets\models 目录下的某个 state 文件名 |
参考的 API 请求主体
{
"default": false,
"id": "00000000-0000-0000-0000-000000000000",
"name": "中文单轮对话",
"path": "rwkv-x060-chn_single_round_qa-1B6-20240516-ctx2048.state"
}
返回结果说明:
- 该 API 没有直接的返回值
- 响应状态码 200 表示请求成功
- 如果指定了 default 为 true,该 state 会立即生效
- state 文件的加载状态可在部署 Ai00 服务的终端查看
admin/models/unload
API 功能:关闭当前已加载的模型和 Ai00 服务。
API 地址:(get)http://localhost:65530/admin/models/unload
返回结果说明:
- 该 API 没有直接的返回值
- 响应状态码 200 表示请求成功
- 卸载成功后,需要重新加载模型才能继续使用服务
- 卸载状态可在部署 Ai00 服务的终端查看
api/adapters
API 功能:返回当前设备所有的 GPU 和驱动,以用于加载模型时指定 GPU。
API 地址:(get)http://localhost:65530/api/adapters
参考的 API 返回结果
[
"AMD Radeon 780M Graphics (Vulkan)",
"AMD Radeon 780M Graphics (Vulkan)",
"AMD Radeon 780M Graphics (Dx12)",
"AMD Radeon 780M Graphics (Dx12)",
"AMD Radeon 780M Graphics (Gl)"
]
返回结果说明:
- 返回一个字符串数组,每个元素代表一个可用的 GPU 设备和其驱动类型
- 数组中的每个元素格式为:
"GPU名称 (驱动类型)"
,如"AMD Radeon 780M Graphics (Vulkan)"
- 数组的索引(从 0 开始),可用于
admin/models/load
API 中的adapter
参数,例如"adapter": {"Manual": 0}
指定使用第一个 GPU
截至 0.5.9 版本,Ai00 仅支持 Vulkan 驱动,不再支持 OpenGL 和 DirectX 驱动。
api/auth/exchange
API 功能:切换带管理员权限的账号,app_id
和 app_secret
需提前在 config.toml
中配置。
API 地址:(post)http://localhost:65530/api/auth/exchange
参数列表:
参数名称 | 是否可选 | 类型 | 参数解释 |
---|---|---|---|
app_id | 必选 | string | 在 config.toml 中配置的 app_id |
app_secret | 必选 | string | 在 config.toml 中配置的 app_secret |
参考的 API 请求主体
{
"app_id": "admin",
"app_secret": "ai00_is_good"
}
参考的 API 返回结果
{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzaWQiOiJhZG1pbiIsImV4cCI6MTczMjM1MjMwMH0.06fDScO-9GxF6rlq1v7MaC608uKg8qNN-TWZ8HvyZDk",
"code": 200,
"message": "SUCCESS"
}
返回结果说明:
token
: 生成的 JWT 认证令牌,用于后续 API 请求的身份验证code
: 状态码,200 表示成功message
: 状态信息,"SUCCESS" 表示成功
Ai00 的采样方法
Ai00 默认使用 Nucleus (又名 top_k )采样方法,这也是 RWKV 模型的默认解码方式。但除了 Nucleus, Ai00 也额外支持 Mirostat 和 Typical 两种采样方式。
不同的采样方法有不同的解码参数,调整模型的各类解码参数,将会影响模型生成的内容风格、内容质量等指标。
以下是 Ai00 三种采样方式的简要描述,和对应的模型解码参数:
Nucleus 采样
Nucleus (又名 top_k )采样方法是通过累积概率(top_p)来选择模型生成的词汇,确保文本多样化且不偏离主题。
Nucleus 采样支持如下解码参数:
参数名称 | 类型 | 参数解释 |
---|---|---|
frequency_penalty | number | 存在惩罚,惩罚已经出现过的,减少它们再次出现的机会 |
penalty | integer | 惩罚半衰期,模型在输出足够的字数后调整 penalty_decay,不建议修改 |
penalty_decay | number | 频率的衰减参数,在每一步生成中逐步减小惩罚值,范围 [0.99, 0.999],不建议修改 |
presence_penalty | number | 频率惩罚,惩罚出现频率较高的词,减少它们频繁出现的机会 |
temperature | number | 采样温度(可以理解为随机性),数值越大随机性越强、更具创造力,也可能导致上下文不连贯 |
top_k | integer | 模型生成内容时的候选词数量(类似于输入法的候选词数量) |
top_p | number | 模型生成的累积概率,这个值越大生成的内容更多样化,但也更容易偏离对话主题甚至胡言乱语 |
在 Ai00 的 API 请求中,标准的 Nucleus 采样格式如下:
{
"sampler_override": {
"frequency_penalty": 0.3,
"penalty": 400,
"penalty_decay": 0.99654026,
"presence_penalty": 0.3,
"temperature": 1,
"top_k": 128,
"top_p": 0.5,
"type": "Nucleus"
}
}
Mirostat 采样
Mirostat 采样通过动态调整熵(随机性)来平衡创造性和连贯性。
参数名称 | 类型 | 参数解释 |
---|---|---|
Rate | number | 模型调整随机性的速度,较高的 rate 值会让模型更快适应新的上下文,但可能导致回答的主题不连贯 |
tau | number | 模型生成文本时的目标随机性,较高的 tau 值会导致模型生成的文本更有创造性和多样性,但可能导致内容不太连贯。 |
在 Ai00 的 API 请求中,标准的 Mirostat 采样格式如下:
{
"sampler_override": {
"Rate": 0.09,
"tau": 0.5,
"type": "Mirostat"
}
}
Typical 采样
Typical 采样通过选择上下文中最有代表性的词,以避免极端概率导致的内容脱轨。
参数名称 | 类型 | 参数解释 |
---|---|---|
frequency_penalty | number | 存在惩罚,惩罚已经出现过的词,减少它们再次出现的机会 |
penalty | integer | 惩罚半衰期,模型在输出足够的字数后调整 penalty_decay,不建议修改 |
penalty_decay | number | 频率的衰减参数,在每一步生成中逐步减小惩罚值,范围 [0.99, 0.999],不建议修改 |
presence_penalty | number | 频率惩罚,惩罚出现频率较高的词,减少它们频繁出现的机会 |
temperature | number | 采样温度(可以理解为随机性),数值越大随机性越强、更具创造力,也可能导致上下文不连贯 |
top_k | integer | 模型生成内容时的候选词数量(类似于输入法的候选词数量) |
tau | number | 模型生成文本时的目标随机性,较高的 tau 值会导致模型生成的文本更有创造性和多样性,但可能导致内容不太连贯。 |
在 Ai00 的 API 请求中,标准的 Typical 采样格式如下:
{
"sampler_override": {
"frequency_penalty": 0.3,
"penalty": 400,
"penalty_decay": 0.99654026,
"presence_penalty": 0.3,
"temperature": 1,
"top_k": 128,
"tau": 5,
"type": "Typical"
}
}