tckm.yan/aha

Fork 0

Files

T

jhqxxx 69af1ceba5 update doc

2026-05-30 13:19:58 +08:00

17 KiB

Raw Blame History

API 参考

AHA REST API 的完整参考。

概述

AHA 提供了 OpenAI 兼容的 REST API 用于运行 AI 模型推理。所有端点遵循标准 HTTP 约定并返回 JSON 响应。

基础 URL

默认情况下，API 服务器运行在：

http://127.0.0.1:10100

您可以在启动服务时自定义：

aha cli -m Qwen/Qwen3-0.6B -a 0.0.0.0 -p 8080

身份验证

目前，AHA 不需要身份验证。所有端点在配置的地址/端口上公开访问。

安全提示：如果您将 API 暴露到外部网络，请考虑通过反向代理（如 nginx、traefik）实现身份验证。

内容类型

所有请求应使用：

Content-Type: application/json

响应格式

成功响应遵循此结构：

{
  "data": { ... },
  "model": "model-name",
  "usage": {
    "total_tokens": 30
  }
}

错误响应：

{
  "error": {
    "message": "错误描述",
    "type": "error_type",
    "code": "error_code"
  }
}

端点

健康检查

检查服务健康状态。此端点适用于容器编排（Kubernetes）、负载均衡器和监控系统。

端点

GET /health

响应

健康 (HTTP 200):

{
  "status": "ok"
}

不健康 (HTTP 503):

{
  "status": "unhealthy",
  "error": "model not initialized"
}

示例

curl http://127.0.0.1:10100/health

模型列表

获取当前加载的模型信息（OpenAI API 兼容格式）。

端点

GET /models

响应

成功 (HTTP 200):

{
  "object": "list",
  "data": [
    {
      "id": "Qwen/Qwen3-0.6B",
      "object": "model",
      "created": null,
      "owned_by": "Qwen"
    }
  ]
}

未初始化 (HTTP 503):

{
  "error": "model not initialized"
}

字段

字段	类型	描述
`object`	string	固定值："list"
`data`	array	模型对象数组（当前仅包含一个已加载的模型）
`id`	string	模型标识符（kebab-case，如 "Qwen/Qwen3-0.6B"）
`object`	string	固定值："model"
`created`	integer\|null	Unix 时间戳（当前为 null）
`owned_by`	string	模型所有者/组织名称

示例

curl http://127.0.0.1:10100/models

对话补全

生成对话补全或文本响应。

端点

POST /chat/completions 
POST /v1/chat/completions

两个端点使用相同的处理函数并返回相同的响应。/v1/chat/completions 路径遵循 OpenAI 的标准 API 约定。

请求体

参数	类型	必需	描述
`model`	string	是	模型标识符（如 "Qwen/Qwen3-0.6B"）
`messages`	array	是	消息对象数组
`temperature`	number	否	采样温度（0-2，默认：1）
`top_p`	number	否	核采样（0-1，默认：1）
`max_tokens`	integer	否	要生成的最大令牌数
`stream`	boolean	否	启用流式传输（默认：true）

消息对象

字段	类型	必需	描述
`role`	string	是	"system"、"user" 或 "assistant"
`content`	string/array	是	消息内容（字符串或多模态数组）

多模态内容

对于视觉/音频模型，内容可以是数组：

{
  "role": "user",
  "content": [
    {"type": "text", "text": "描述这张图片"},
    {"type": "image", "image_url": {"url": "file:///path/to/image.jpg"}}
  ]
}

支持的内容类型：

text - 文本内容
image - 图像文件（file://,base64://, https:// 或 http://）
audio - 音频文件（file://,base64://, https:// 或 http://）

示例

简单对话：

curl http://127.0.0.1:10100/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-0.6B",
    "messages": [
      {"role": "user", "content": "你好！"}
    ]
  }'

带系统消息：

curl http://127.0.0.1:10100/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-0.6B",
    "messages": [
      {"role": "system", "content": "你是一个有用的助手。"},
      {"role": "user", "content": "用一句话解释 Rust。"}
    ],
    "max_tokens": 50,
    "temperature": 0.7
  }'

视觉理解：

curl http://127.0.0.1:10100/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-VL-2B-Instruct",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "这张图片里有什么？"},
          {"type": "image", "image_url": {"url": "file:///path/to/image.jpg"}}
        ]
      }
    ]
  }'

OCR（文本提取）：

curl http://127.0.0.1:10100/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-OCR",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "提取所有文本"},
          {"type": "image", "image_url": {"url": "file:///path/to/document.png"}}
        ]
      }
    ]
  }'

ASR（语音识别）：

curl http://127.0.0.1:10100/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ZhipuAI/GLM-ASR-Nano-2512",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "转写这段音频"},
          {"type": "audio", "audio_url": {"url": "file:///path/to/audio.wav"}}
        ]
      }
    ]
  }'

提示：支持 OpenAI 标准的音频转录接口，使用 multipart/form-data 上传文件。详见语音转写章节。

流式响应：

curl http://127.0.0.1:10100/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-0.6B",
    "messages": [
      {"role": "user", "content": "给我讲个故事"}
    ],
    "stream": true
  }'

流式响应作为服务器发送事件（SSE）发送：

data: {"id": "1", "choices": [{"delta": {"content": "从前"}}]}

data: {"id": "1", "choices": [{"delta": {"content": "有"}}]}

data: [DONE]

响应

非流式：

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "Qwen/Qwen3-0.6B",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！今天我能帮你什么？"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "total_tokens": 19
  }
}

语音生成

从文本生成语音（文本转语音）。

端点

POST /audio/speech

请求体

参数	类型	必需	描述
`model`	string	是	模型标识符（如 "OpenBMB/VoxCPM-0.5B1.5"）
`messages`	array	是	消息对象数组

示例

curl http://127.0.0.1:10100/audio/speech \
  -H "Content-Type: application/json" \
  -d '{
    "model": "OpenBMB/VoxCPM-0.5B1.5",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "你好，这是 AHA 在说话。"}
        ]
      }
    ]
  }'

响应

以 base64 WAV 格式返回音频数据。

语音转写

将音频文件转录为文本（自动语音识别）。

此接口提供符合 OpenAI 标准的音频转录功能，使用 multipart/form-data 格式。

端点

POST /audio/transcriptions
POST /v1/audio/transcriptions

两个端点使用相同的处理函数并返回相同的响应。/v1/audio/transcriptions 路径遵循 OpenAI 的标准 API 约定。

请求参数

参数	类型	必需	描述
`file`	file	是	要转录的音频文件 (wav, mp3, m4a 等)
`model`	string	否	模型标识符（可选，被忽略 - 使用已加载的模型）
`language`	string	否	语言代码（如 "zh"、"en"、"yue"）
`prompt`	string	否	引导转录的可选文本（未实现，被忽略）
`response_format`	string	否	响应格式，仅支持 "json" 或 "text"（默认："json"）
`temperature`	number	否	采样温度 (0.0 到 1.0，默认：0.0)

支持的语言

代码	语言	代码	语言
`zh`	中文	`en`	英语
`yue`	粤语	`ar`	阿拉伯语
`de`	德语	`fr`	法语
`es`	西班牙语	`pt`	葡萄牙语
`id`	印尼语	`it`	意大利语
`ko`	韩语	`ru`	俄语
`th`	泰语	`vi`	越南语
`ja`	日语	`tr`	土耳其语
`hi`	印地语	`ms`	马来语
`nl`	荷兰语	`sv`	瑞典语
`da`	丹麦语	`fi`	芬兰语
`pl`	波兰语	`cs`	捷克语
`fil`	菲律宾语	`fa`	波斯语
`el`	希腊语	`ro`	罗马尼亚语
`hu`	匈牙利语	`mk`	马其顿语

示例

基本转录：

curl -X POST http://127.0.0.1:10100/audio/transcriptions \
  -H "Authorization: Bearer NO_NEED" \
  -F file="@./audio.wav" \
  -F model="Qwen/Qwen3-ASR-0.6B"

指定语言：

curl -X POST http://127.0.0.1:10100/v1/audio/transcriptions \
  -H "Authorization: Bearer NO_NEED" \
  -F file="@./chinese_audio.wav" \
  -F model="Qwen/Qwen3-ASR-0.6B" \
  -F language="zh"

设置温度参数：

curl -X POST http://127.0.0.1:10100/v1/audio/transcriptions \
  -H "Authorization: Bearer NO_NEED" \
  -F file="@./audio.wav" \
  -F model="Qwen/Qwen3-ASR-0.6B" \
  -F temperature="0.0"

响应

成功 (HTTP 200):

{
  "text": "从音频文件转录的文本"
}

错误 (HTTP 400):

{
  "error": {
    "message": "Audio file is required",
    "type": "invalid_request_error",
    "code": "missing_file"
  }
}

错误 (HTTP 503):

{
  "error": {
    "message": "Model not initialized",
    "type": "service_unavailable",
    "code": "model_not_loaded"
  }
}

文件上传限制

最大音频文件大小：100 MB

图像背景移除

从图像中移除背景。

端点

POST /images/remove_background

请求体

参数	类型	必需	描述
`model`	string	是	模型标识符（如 "AI-ModelScope/RMBG-2.0"）
`messages`	array	是	消息对象数组

示例

从文件：

curl http://127.0.0.1:10100/images/remove_background \
  -H "Content-Type: application/json" \
  -d '{
    "model": "AI-ModelScope/RMBG-2.0",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "image", "image_url": {"url": "file:///path/to/document.jpg"}}
        ]
      }
    ]
  }'

从 Base64：

curl http://127.0.0.1:10100/images/remove_background \
  -H "Content-Type: application/json" \
  -d '{
    "model": "AI-ModelScope/RMBG-2.0",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "image", "image_url": {"url": "base64://$(base64 -w 0 photo.png)"}}
        ]
      }
    ]
  }'

响应

以base64 PNG 格式返回处理后的图像。

嵌入

生成文本嵌入向量。

端点

POST /embeddings
POST /v1/embeddings

请求体

参数	类型	必需	描述
`model`	string	否	模型标识符
`input`	string 或 array	是	要嵌入的文本或文本数组

示例

单个文本：

curl http://127.0.0.1:10100/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Hello world"
  }'

多个文本：

curl http://127.0.0.1:10100/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "input": ["Hello world", "How are you?", "Goodbye"]
  }'

响应

成功 (HTTP 200):

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.1, 0.2, 0.3, ...]
    }
  ],
  "model": "model-name"
}

错误 (HTTP 400):

{
  "error": "embedding input must be a string or an array of strings"
}

重排

对文档列表根据查询进行重新排序。

端点

POST /rerank
POST /v1/rerank

请求体

参数	类型	必需	描述
`model`	string	否	模型标识符
`query`	string	是	查询文本
`documents`	array	是	要重排序的文档文本数组
`top_n`	int	否	返回前N个结果（可选）

示例

基础重排序：

curl http://127.0.0.1:10100/rerank \
  -H "Content-Type: application/json" \
  -d '{
    "query": "人工智能",
    "documents": [
      "机器学习是一种人工智能技术",
      "苹果是一种水果",
      "深度学习属于人工智能领域"
    ]
  }'

限制返回数量：

curl http://127.0.0.1:10100/rerank \
  -H "Content-Type: application/json" \
  -d '{
    "query": "人工智能",
    "documents": [
      "机器学习是一种人工智能技术",
      "苹果是一种水果", 
      "深度学习属于人工智能领域"
    ],
    "top_n": 2
  }'

响应

成功 (HTTP 200):

{
  "object": "list",
  "model": "model-name",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.95,
      "document": "机器学习是一种人工智能技术"
    },
    {
      "index": 2,
      "relevance_score": 0.87,
      "document": "深度学习属于人工智能领域"
    }
  ]
}

错误 (HTTP 400):

{
  "error": "rerank query cannot be empty"
}

字段说明

字段	类型	描述
`model`	string	模型标识符
`object`	string	固定值："list"
`results`	array	重排序结果数组
`index`	int	原始文档索引
`relevance_score`	f32	相关性分数（越高越相关）
`document`	string	原始文档文本

优雅关机

优雅地关闭 AHA 服务器。此端点启动优雅关闭流程：

停止接受新连接
等待现有请求完成（最多 1 秒）
清理 PID 文件
退出进程

端点

POST /shutdown

请求体

无（空请求）

响应

成功 (HTTP 200):

{
  "message": "Shutting down..."
}

禁止访问 (HTTP 403):

当不允许远程关闭时：

{
  "error": "Remote shutdown not allowed. Use --allow-remote-shutdown flag to enable (not recommended)."
}

安全性

默认情况下，关机端点仅允许来自 localhost (127.0.0.1) 的请求。要启用远程关闭，请使用 --allow-remote-shutdown 标志启动服务器：

aha serv -m Qwen/Qwen3-0.6B --allow-remote-shutdown

警告： 除非有适当的安全措施，否则不建议在生产环境中启用远程关闭。

示例

curl -X POST http://127.0.0.1:10100/shutdown

日志记录

所有关机请求都会记录到 stderr，格式如下：

[SHUTDOWN] Shutdown requested (remote_allowed: false)

错误处理

错误代码

代码	描述
400	错误请求 - 无效参数
404	未找到 - 模型或端点未找到
500	内部服务器错误 - 模型推理错误
503	服务不可用 - 模型未加载

错误响应格式

{
  "error": {
    "message": "未找到模型 'unknown-model'",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

速率限制

目前，AHA 不实现速率限制。服务器可以处理并发请求，仅受系统资源限制。

文件上传限制

字符串数据：5 MB
文件上传：100 MB

OpenAI 兼容性

AHA 的文本生成 API 设计与 OpenAI 的 API 格式兼容。多模态 API 源自文本生成 API，仅做了少量改动：

Python 示例

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:10100",
    api_key="dummy"  # 不使用但库需要
)

response = client.chat.completions.create(
    model="Qwen/Qwen3-0.6B",
    messages=[
        {"role": "user", "content": "你好！"}
    ]
)

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

JavaScript 示例

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://127.0.0.1:10100',
  apiKey: 'dummy'  // 不使用但需要
});

const response = await client.chat.completions.create({
  model: 'Qwen/Qwen3-0.6B',
  messages: [{ role: 'user', content: '你好！' }]
});

console.log(response.choices[0].message.content);

最佳实践

1. 对长响应使用流式传输

对于长文本生成，使用流式传输增量获取响应：

curl ... -d '{"stream": true, ...}'

2. 设置适当的令牌限制

防止过长的响应：

{
  "max_tokens": 500
}

3. 调整温度

控制响应创造性：

0.0-0.3：确定性、专注
0.4-0.7：平衡（默认：1.0）
0.8-2.0：创造性、多样

4. 使用系统消息

使用系统消息设置行为：

{
  "messages": [
    {"role": "system", "content": "你是一个技术写作助手。"},
    {"role": "user", "content": "..."}
  ]
}

另见

快速入门 - 快速入门指南
CLI 参考 - 命令行使用
安装 - 安装指南
开发 - 贡献指南

17 KiB Raw Blame History Unescape Escape

API 参考

概述

基础 URL

身份验证

内容类型

响应格式

端点

健康检查

端点

响应

示例

模型列表

端点

响应

字段

示例

对话补全

端点

请求体

消息对象

多模态内容

示例

响应

语音生成

端点

请求体

示例

响应

语音转写

端点

请求参数

支持的语言

示例

响应

文件上传限制

图像背景移除

端点

请求体

示例

响应

嵌入

端点

请求体

示例

响应

重排

端点

请求体

示例

响应

字段说明

优雅关机

端点

请求体

响应

安全性

示例

日志记录

错误处理

错误代码

错误响应格式

速率限制

文件上传限制

OpenAI 兼容性

Python 示例

JavaScript 示例

最佳实践

1. 对长响应使用流式传输

2. 设置适当的令牌限制

3. 调整温度

4. 使用系统消息

另见

17 KiB

Raw Blame History