闻达(wenda)HTTP API 实战指南:/chat/completions 接口规范与底层实现解析

原创2026-10-14 21:51:141,843 阅读
文章标签:AI 应用大模型RAG后端

闻达(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))
    ...

关键点:

  1. prompt 提取:取 messages 数组最后一条的 content 作为本次提问;
  2. 历史转换:将 messages[0:len(messages)-1] 中的消息转成对话历史。注意 assistant 角色被改写为 AI(闻达内部约定的模型角色名),user 保持不变,其他角色被跳过;
  3. 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\n
    
    末尾的 data: <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),表示知识库上下文步长。

七、部署与调用注意事项

  1. 服务地址:确认服务已启动且端口可访问。默认端口 17860,可通过命令行 -p 参数覆盖,例如 python wenda.py -p 18000 后请求地址相应变为 http://127.0.0.1:18000/chat/completions。
  2. 模型加载:服务启动时会以独立线程加载模型(wenda.py),首次请求前需等待"模型加载完成"提示,否则推理会失败。
  3. 跨域:Bottle 路由中调用了 allowCROS() 设置 CORS 头,浏览器端跨域调用一般无需额外处理。
  4. 流式响应头:/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)。
  5. 排队体验:高并发下新请求可能进入排队并收到等待提示,可结合 /chat_now 接口在客户端展示排队状态。

八、小结

闻达的 /chat/completions 接口遵循"前端与 API 共用推理管线"的设计:HTTP 入口负责参数规范化(提取 prompt、转换历史角色),WebSocket /ws 负责排队与模型推理,stream 参数控制最终以完整 JSON 还是 SSE 流式返回。掌握本文的请求格式、参数语义与源码调用链之后,你可以便捷地把闻达接入自建 Web 应用、命令行工具或自动化脚本,在保持模型私有化部署的同时获得与 OpenAI 风格接口一致的调用体验。

登录后查看全文
wenda