NeuralWatt2API

将 NeuralWatt Chat 接口转换为 OpenAI、Claude 和 Gemini 兼容协议的轻量代理。支持普通响应、SSE 流式响应、多模态内容、函数工具调用、推理内容及 Token/缓存用量转换。

主要能力

• OpenAI Chat Completions 与 Responses API。
• Claude Messages API，包括标准流式事件。
• Gemini GenerateContent 与 StreamGenerateContent API。
• OpenAI、Claude、Gemini 三种模型列表格式。
• 文本、图片、函数工具调用及工具结果转换。
• Token 总量、缓存读取、缓存写入和推理 Token 映射。
• NeuralWatt 定价、能耗 SSE 注释透传。
• 可选的客户端 API Key 校验。
• 端口占用进程详情和解决命令提示。

接口

协议	方法	路径	说明
OpenAI	POST	/v1/chat/completions	Chat Completions，支持流式
OpenAI	POST	/v1/responses	Responses，支持流式
OpenAI/Claude	GET	/v1/models	默认返回 OpenAI 格式；携带 anthropic-version 返回 Claude 格式
Claude	POST	/v1/messages	标准 Messages 接口
Claude	POST	/v1/claude/messages	Messages 兼容别名
Gemini	POST	/v1beta/models/{model}:generateContent	普通响应
Gemini	POST	/v1beta/models/{model}:streamGenerateContent	SSE 流式响应
Gemini	GET	/v1beta/models	Gemini 模型列表
Gemini	POST	/v1/gemini/chat	兼容别名

Gemini 同时支持 /v1/models/{model}:generateContent、/v1/models/{model}:streamGenerateContent 和 /v1/models/gemini。

环境要求

• Python 3.10+
• 可访问 portal.neuralwatt.com 和 api.neuralwatt.com
• 有效的 NeuralWatt Cookie

快速启动

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python main.py

默认监听：

http://localhost:10086

也可使用 Uvicorn：

uvicorn main:app --host 0.0.0.0 --port 10086

配置

默认读取项目根目录的 config.yaml：

proxy:
  target_url: "https://portal.neuralwatt.com/api/chat"
  models_url: "https://api.neuralwatt.com/v1/models"
  models_cache_ttl: 300
  timeout: 300
  port: 10086
  host: "0.0.0.0"
  model: "glm-5.2"
  temperature: 0.7
  max_tokens: 8150
  top_p: 1.0
  stream: true
  api_key: ""
  cookies:
    cf_clearance: ""
    nw_session: ""
    ph_posthog: ""
  additional_headers:
    accept: "application/json, text/event-stream"
    content-type: "application/json"

配置项	说明
target_url	NeuralWatt Chat 上游地址
models_url	NeuralWatt 官方模型列表地址
models_cache_ttl	模型列表缓存秒数
timeout	上游请求总超时秒数
port、host	本地监听端口和地址
model	请求未指定模型时使用的默认模型
temperature、top_p	OpenAI Chat 默认采样参数
max_tokens	协议请求未指定输出上限时的默认值
stream	OpenAI Chat 未指定 stream 时的默认值
api_key	客户端访问本代理所需密钥；空值表示不校验
cookies	NeuralWatt 会话 Cookie
additional_headers	发送给 Chat 上游的附加请求头

环境变量优先于 config.yaml 中的 Cookie：

CF_CLEARANCE=
NW_SESSION=
PH_POSTHOG=
CONFIG_PATH=config.yaml

不要把有效 Cookie 提交到公开仓库。

客户端认证

当 proxy.api_key 非空时，请求必须提供匹配的密钥。支持以下方式：

Authorization: Bearer your-api-key

x-api-key: your-api-key

x-goog-api-key: your-api-key

Gemini 也支持查询参数：

?key=your-api-key

proxy.api_key 为空时不校验客户端密钥。

模型数据

/v1/models 读取 NeuralWatt 官方模型 API，不维护容易过期的本地模型表。默认缓存 300 秒。

OpenAI 格式原样保留官方字段：

• id、object、created、owned_by
• max_model_len
• metadata.display_name、description、provider
• metadata.pricing
• metadata.capabilities
• metadata.limits

截至 2026-07-29，官方接口主要上下文限制如下：

模型	有效上下文	明确的最大输出
deepseek-v4-flash	1,048,560	65,536
glm-5.2	1,048,560	未单独限制
glm-5.2-fast	1,048,560	未单独限制
glm-5.2-short	199,984	32,000
glm-5.2-short-fast	199,984	32,000
gemma-4-31b	262,128	16,384
kimi-k2.6、kimi-k2.6-fast	262,128	未单独限制
kimi-k2.7-code、kimi-k2.7-code-fast	262,128	未单独限制
qwen3.5-397b、qwen3.5-397b-fast	262,128	未单独限制
qwen3.6-35b、qwen3.6-35b-fast	131,056	未单独限制

“未单独限制”表示上游没有设置独立输出上限，仍受总上下文限制。实际数据以 /v1/models 当前返回为准。官方接口当前返回的 created 是 0，本项目不会伪造创建时间。

请求示例

OpenAI Chat Completions

普通响应：

curl http://localhost:10086/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.2",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": false,
    "max_tokens": 1024
  }'

流式响应：

curl -N http://localhost:10086/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.2-short-fast",
    "messages": [{"role": "user", "content": "简要介绍 Python"}],
    "stream": true
  }'

OpenAI Responses

curl http://localhost:10086/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.2",
    "instructions": "回答要简洁",
    "input": "你好",
    "max_output_tokens": 1024
  }'

Claude Messages

curl http://localhost:10086/v1/messages \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "glm-5.2",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "你好"}],
    "stream": false
  }'

Gemini GenerateContent

curl 'http://localhost:10086/v1beta/models/glm-5.2:generateContent' \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "你好"}]
    }],
    "generationConfig": {
      "maxOutputTokens": 1024,
      "temperature": 0.7
    }
  }'

流式响应：

curl -N 'http://localhost:10086/v1beta/models/glm-5.2:streamGenerateContent?alt=sse' \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"你好"}]}]}'

模型列表

curl http://localhost:10086/v1/models
curl http://localhost:10086/v1/models -H "anthropic-version: 2023-06-01"
curl http://localhost:10086/v1beta/models

Token 用量与缓存

所有协议的用量都来自 NeuralWatt 上游响应，不使用字符数估算。

协议	输入/输出/总量	缓存读取	缓存写入	推理 Token
OpenAI Chat	prompt_tokens、completion_tokens、total_tokens	prompt_tokens_details.cached_tokens	prompt_tokens_details.cache_creation_tokens	completion_tokens_details.reasoning_tokens
OpenAI Responses	input_tokens、output_tokens、total_tokens	input_tokens_details.cached_tokens	input_tokens_details.cache_creation_tokens	output_tokens_details.reasoning_tokens
Claude	input_tokens、output_tokens	cache_read_input_tokens	cache_creation_input_tokens、cache_creation	计入上游输出用量
Gemini	promptTokenCount、candidatesTokenCount、totalTokenCount	cachedContentTokenCount	cacheCreationTokenCount	thoughtsTokenCount

说明：

• OpenAI 和 Gemini 官方协议没有缓存写入字段，cache_creation_tokens 与 cacheCreationTokenCount 是本项目兼容扩展。
• 上游未报告缓存写入时返回 0，不会把普通未命中 Token 当成缓存写入。
• 流式请求会自动向上游启用 stream_options.include_usage，最终事件包含完整用量。
• NeuralWatt 当前通常报告缓存命中量，但不报告缓存创建量。
• NeuralWatt 当前只报告聚合的 completion_tokens，不单独报告推理 Token，且流式 token_ids 通常为 null。纯推理输出可准确归入推理 Token；推理与正文混合且无法精确拆分时，reasoning_tokens/thoughtsTokenCount 返回 null，不会伪造数值。

多模态与工具调用

• OpenAI Chat 请求直接保留标准消息、图片和函数工具字段。
• OpenAI Responses 支持文本、图片、函数调用和函数调用结果转换。
• Claude 支持 text、image、tool_use 和 tool_result 内容块。
• Gemini 支持 text、inlineData、fileData、functionCall 和 functionResponse。
• Claude system 与 Gemini systemInstruction 会转换为上游系统消息。

最终能力仍受所选 NeuralWatt 模型限制，请查看 /v1/models 中的 metadata.capabilities。当前代理只转换函数工具；OpenAI Responses 内置网页搜索、文件搜索、计算机控制等托管工具不会由本项目执行。

流式响应

• OpenAI Chat：输出 chat.completion.chunk，以 data: [DONE] 结束。
• OpenAI Responses：输出 response.created、增量事件和 response.completed/response.incomplete。
• Claude：输出 message_start、内容块事件、message_delta 和 message_stop。
• Gemini：输出 GenerateContentResponse SSE 数据块。
• NeuralWatt 的 pricing、energy 信息作为 SSE 注释保留，标准客户端会自动忽略注释。

错误格式

• OpenAI 接口返回 OpenAI error 对象。
• Claude 接口返回 Anthropic type: error 对象。
• Gemini 接口返回 Google 风格 error 对象。
• 上游 HTTP 状态码会尽量原样返回；连接失败返回 502。

端口被占用

使用 python main.py 启动时会提前检查端口，并打印 PID、用户、父进程、运行时长、监听地址、完整启动命令和处理命令。

Ctrl+C 会向前台进程发送中断信号并正常退出；Ctrl+Z 只会暂停进程，终端显示 suspended，进程和监听端口仍然存在。暂停后可在原终端执行：

jobs -l
fg %任务号

恢复到前台后按 Ctrl+C 退出。也可按 PID 结束暂停进程：

kill -TERM <PID>
kill -CONT <PID>

手动检查：

lsof -nP -iTCP:10086 -sTCP:LISTEN

正常结束占用进程：

kill <PID>

进程拒绝退出时再强制结束：

kill -9 <PID>

也可修改 config.yaml 中的 proxy.port。

测试

python -m unittest -v

测试覆盖协议请求转换、普通响应、流式事件、函数工具、Token/缓存用量和模型列表转换。

项目文件

main.py          服务与协议转换
config.yaml      服务配置
.env.example     环境变量模板
test_main.py     单元测试
requirements.txt Python 依赖

上游资料

• NeuralWatt 模型目录
• NeuralWatt 模型 API 文档
• NeuralWatt API 文档