闻达(wenda)HTTP API 实战指南:/chat/completions 接口规范与底层实现解析
闻达(wenda)HTTP API 实战指南:/chat/completions 接口规范与底层实现解析
本文是闻达(wenda)LLM 调用平台的 API 接入指南,聚焦于平台对外提供的 POST /chat/completions 聊天接口:从请求地址、请求头、请求体 JSON 结构与参数语义,到 Node.js、PHP 两种语言的完整调用示例,再深入到 wenda.py 的路由实现与 WebSocket 桥接原理。读完本文,你可以将闻达作为私有化 LLM 后端接入任意应用(Web 前端、脚本、自动化任务),并理解流式/非流式两种返回格式的差异与选择依据。
一、接口概览与端点挂载方式
闻达通过 FastAPI + Bottle 双层框架提供服务:Bottle 负责业务路由,FastAPI 负责 WebSocket 与静态资源。在 wenda.py 中,Bottle 应用被同时挂载到 /chat/ 与 /api/ 两个前缀下:
app.mount(path="/chat/", app=WSGIMiddleware(bottle.app[0]))
app.mount(path="/api/", app=WSGIMiddleware(bottle.app[0]))
这意味着 Bottle 内定义的 /completions 路由,同时可通过 /chat/completions 与 /api/completions 两个地址访问。官方文档采用 /chat/completions 作为对外约定地址。
接口的默认服务端口为 17860,由 example.config.yml 中的 port: 17860 指定。因此本地部署的完整请求地址为:
http://127.0.0.1:17860/chat/completions
若服务部署在远程主机,将 Host 替换为对应 IP 或域名即可:http://{Host:Port}/chat/completions。
二、请求规范
2.1 请求头
/chat/completions 为 POST 接口,请求头只需声明 JSON 内容类型:
{
"Content-Type": "application/json"
}
2.2 请求体
请求体为 JSON 格式,支持 model、stream、messages 三个顶层字段,示例:
{
"model": "rwkv",
"stream": false,
"messages": [
{
"role": "user",
"content": "树上有9只鸟,猎人开枪打死1只,树上还剩几只鸟?"
},
{
"role": "assistant",
"content": "题目中提到有9只鸟,猎人打死了其中的1只,所以树上剩下的鸟的数量为8。"
},
{
"role": "user",
"content": "错了,树上不再剩下鸟。因为猎人开枪的声音会把其它的鸟都吓飞。"
}
]
}
2.3 参数说明
| 参数 | 类型 | 必填 | 含义 |
|---|---|---|---|
| model | string |
可选 | 选择使用的模型。目前该字段暂未使用,平台实际使用的模型由服务端配置(config.yml 中的 llm_type)决定,见下文"四、模型选择与配置"。 |
| stream | boolean |
可选 | 是否使用流式输出返回。true 时以 SSE(Server-Sent Events)方式逐段返回生成结果,false 时返回完整 JSON 结果。 |
| messages | array |
必填 | 当前对话的信息列表,支持多轮对话。 |
messages 数组中每个元素包含两个必填字段:
| 参数名 | 类型 | 必填 | 含义 |
|---|---|---|---|
| role | string |
必填 | 信息的来源作者。取值包括 user、assistant,分别代表用户和模型。 |
| content | string |
必填 | 信息内容。所有 content 都必须包含内容,不能为空。 |
需要注意:messages 数组的最后一条将被作为本次要回答的问题(prompt),其前面的若干条则作为对话历史拼接进上下文。具体处理逻辑见下文源码解析。
三、调用示例
3.1 Node.js 示例
使用 node-fetch 发起请求:
const fetch = require("node-fetch");
fetch("http://127.0.0.1:17860/chat/completions", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "rwkv",
stream: false,
messages: [
{
role: "user",
content: "树上有9只鸟,猎人开枪打死1只,树上还剩几只鸟?",
},
],
}),
});
3.2 PHP 示例
使用 PHP 内置的 curl 扩展:
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://127.0.0.1:17860/chat/completions');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "{\r\n \"model\": \"rwkv\",\r\n \"stream\": false,\r\n \"messages\": [\r\n {\r\n \"role\": \"user\",\r\n \"content\": \"你好\"\r\n }\r\n ]\r\n}");
$headers = array();
$headers[] = 'Content-Type: application/json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$result = curl_exec($ch);
if (curl_errno($ch)) {
echo 'Error:' . curl_error($ch);
}
curl_close($ch);
PHP 示例中 CURLOPT_POSTFIELDS 传入的字符串即标准请求体 JSON,其字段结构与 2.2 节完全一致,可替换为任意对话内容。
四、模型选择与配置:为什么请求体中的 model 暂时无效
请求体中的 model 字段"目前暂未使用",是因为闻达的模型选择发生在服务端启动阶段而非请求阶段。从源码看:
- plugins/common.py 在启动时解析命令行参数与配置文件,通过
llm_type决定加载哪套模型驱动:LLM = import_module('llms.llm_' + settings.llm_type),并读取对应模型的path、strategy等参数; - example.config.yml 中
llm_type: rwkv即为默认模型类型,其下llm_models.rwkv.path指定模型文件路径(如model/rwkv-x060-3b-world-v2-28%trained-20231208-ctx4k.pth); - 启动时还支持命令行参数覆盖配置:
-c指定配置文件、-p指定端口、-l开启日志、-t指定模型类型(见 plugins/common.py)。
因此,如果你希望通过 API 切换模型,应在服务端通过 -t glm6b 等方式重启服务,而不是在请求体里传 model。
五、源码级解析:/chat/completions 的完整调用链
5.1 路由入口
/completions 路由定义于 wenda.py,核心逻辑如下:
@route('/completions', method=("POST", "OPTIONS"))
def api_chat_box():
response.content_type = "text/event-stream"
...
data = request.json
messages = data.get('messages')
stream = data.get('stream')
prompt = messages[-1]['content']
data['prompt'] = prompt
history = []
for i, old_chat in enumerate(messages[0:len(messages)-1]):
if old_chat['role'] == "user":
history.append(old_chat)
elif old_chat['role'] == "assistant":
old_chat['role'] = "AI"
history.append(old_chat)
...
data['history'] = history
data['level'] = 0
from websocket import create_connection
ws = create_connection("ws://127.0.0.1:"+str(settings.port)+"/ws")
ws.send(json.dumps(data))
...
关键点:
- prompt 提取:取
messages数组最后一条的content作为本次提问; - 历史转换:将
messages[0:len(messages)-1]中的消息转成对话历史。注意assistant角色被改写为AI(闻达内部约定的模型角色名),user保持不变,其他角色被跳过; - WebSocket 桥接:该路由本身并不直接调用模型,而是通过
create_connection建立到ws://127.0.0.1:{settings.port}/ws的内部 WebSocket 连接,把拼接好的{prompt, history, level}数据发送给推理线程——这就是闻达 API 与前端共用同一套推理管线的设计:前端页面同样通过/ws推送请求(见 views/wd_sdk.js 的send_raw函数)。
5.2 WebSocket 推理端点
真正的模型推理发生在 wenda.py 的 @app.websocket('/ws') 中。这里除了执行 LLM.chat_init(history) 与 LLM.chat_one(prompt, history_formatted, max_length, top_p, temperature, data) 之外,还有两个值得注意的机制:
- 默认采样参数:当请求体未显式携带时,服务端使用默认值——
max_length默认2048(最大生成长度)、top_p默认0.7、temperature默认0.9; - 并发排队:服务端维护
users_count数组,结合请求中的level字段做请求排队控制。level值越小优先级越高(/completions路由将level固定为0,即最高优先级);当计算中的用户数超过4 - level时,新请求会收到"正在排队,当前计算中用户数:…剩余时间:…"的提示,直至前序任务完成(见 wenda.py)。
5.3 两种返回格式
在 /completions 路由内部,stream 参数直接决定响应格式:
- 非流式(stream: false):将响应
content_type改为application/json,循环接收 WebSocket 结果并以最后一条为准,返回:{"response": "完整的回答内容"} - 流式(stream: true):保持
text/event-stream,按 SSE 协议逐段返回:
末尾的data: {"response": "逐段生成的文本"}\n\n ... data: [DONE]\n\ndata: <a href="https://link.gitcode.com/i/1c0d7615bc6244fdc9d4483aff54fa97" target="_blank">DONE]是标准的 SSE 结束标记,客户端应据此判断生成完成(见 [wenda.py)。
实际生成过程采用 token 级流式输出:以 RWKV 为例,llms/llm_rwkv.py 的 chat_one 逐 token 采样(受 temperature、top_p、presence_penalty、count_penalty 控制),边生成边 yield 累积文本,因此流式模式下客户端可以做到"打字机"式实时展示。
六、配套接口:更多 HTTP 端点
除了 /chat/completions,wenda.py 还提供了若干可直接调用的配套端点,适合构建更完整的应用:
| 端点 | 方法 | 说明 | 源码位置 |
|---|---|---|---|
/chat/completions |
POST | OpenAI 风格聊天接口(本文主体) | wenda.py |
/chat_stream |
POST | 流式聊天接口,直接返回生成片段(非 SSE 封装) | wenda.py |
/chat |
POST | 聊天接口,阻塞式返回完整结果文本 | wenda.py |
/chat_now |
GET | 查询当前排队中的请求数,返回 {"queue_length": n} |
wenda.py |
/find |
POST | 知识库检索,请求体含 prompt、step,返回检索结果 JSON |
wenda.py |
/ws |
WebSocket | 推理主通道,前端与 API 共用 | wenda.py |
其中 /find 用于知识库问答场景,请求体示例(可参考前端 views/wd_sdk.js 的 find 函数):
{
"prompt": "要检索的问题",
"step": 2
}
step 缺省时取 example.config.yml 中 library.step 的配置值(默认 2),表示知识库上下文步长。
七、部署与调用注意事项
- 服务地址:确认服务已启动且端口可访问。默认端口
17860,可通过命令行-p参数覆盖,例如python wenda.py -p 18000后请求地址相应变为http://127.0.0.1:18000/chat/completions。 - 模型加载:服务启动时会以独立线程加载模型(wenda.py),首次请求前需等待"模型加载完成"提示,否则推理会失败。
- 跨域:Bottle 路由中调用了
allowCROS()设置 CORS 头,浏览器端跨域调用一般无需额外处理。 - 流式响应头:
/completions在两种模式下都会添加Connection: keep-alive、Cache-Control: no-cache、X-Accel-Buffering: no响应头(见 wenda.py),其中X-Accel-Buffering: no用于防止 Nginx 等反向代理缓冲 SSE 数据;FastAPI 中间件还会附加X-Process-Times头记录处理耗时(wenda.py)。 - 排队体验:高并发下新请求可能进入排队并收到等待提示,可结合
/chat_now接口在客户端展示排队状态。
八、小结
闻达的 /chat/completions 接口遵循"前端与 API 共用推理管线"的设计:HTTP 入口负责参数规范化(提取 prompt、转换历史角色),WebSocket /ws 负责排队与模型推理,stream 参数控制最终以完整 JSON 还是 SSE 流式返回。掌握本文的请求格式、参数语义与源码调用链之后,你可以便捷地把闻达接入自建 Web 应用、命令行工具或自动化脚本,在保持模型私有化部署的同时获得与 OpenAI 风格接口一致的调用体验。