企业官网建设流程全解析

如何用 NInfer 部署 OpenAI/Anthropic 兼容 API：本地 LLM 服务搭建实战教程

【免费下载链接】ninferHigh-performance single-GPU inference for selected model checkpoints and GPUs.项目地址: https://gitcode.com/gh_mirrors/ni/ninfer

NInfer是一个面向单张 NVIDIA 显卡的高性能推理引擎，一条命令就能把本地大模型变成OpenAI 兼容 API 服务：ninfer-serve加载一个.ninfer模型工件，即可同时提供 OpenAI Chat Completions / Responses 与 Anthropic Messages 三套 HTTP 接口，让你在完全离线的环境里获得媲美云端的本地 LLM 服务。本教程面向新手，带你从零完成环境准备、服务启动、API 调用到多模态扩展的完整流程。

🎯 为什么选择 NInfer 搭建本地 LLM 服务

NInfer 是 C++/CUDA 从零实现的推理引擎，专注在**单 GPU（RTX 5090）**上榨干所选模型的性能：

• 双协议兼容：同时实现 OpenAI Chat Completions、OpenAI Responses 与 Anthropic Messages 接口，现有 SDK 改个base_url就能接入
• 多模态支持：文本、图像、视频输入走同一套上下文协议
• 长上下文前缀复用：相同的对话前缀自动命中缓存，多轮对话与多用户共享前缀时显著降低首 token 延迟
• 高性能解码：CUDA Graph + 投机解码（MTP/DFlash），官方记录中 Qwen3.6-27B NVFP4 在 8 并发下稳态解码可达 1100+ tok/s（详见 docs/performance.md）

当前提供 Qwen3.6-27B、Qwen3.8-27B（含 NVFP4 量化版）和 Qwen3.6-35B-A3B 五款官方.ninfer工件。

📋 准备工作：环境要求与构建步骤

系统要求一览

一键克隆与构建命令

git clone https://gitcode.com/gh_mirrors/ni/ninfer cd ninfer cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release cmake --build build -j

构建完成后，build/apps/ninfer-serve就是本教程的主角——本地 LLM API 服务程序。注意 NInfer 没有安装包，直接从源码构建目录运行即可。

下载模型工件

.ninfer工件内置模型配置、编码权重与前端资源，开箱即用。以教程示例使用的 Qwen3.8-27B NVFP4 为例，使用 Hugging Face CLI 下载（仓库地址见项目 README.md 中的官方工件列表）：

hf download neroued/Qwen3.8-27B-nvfp4-NInfer \ qwen3_8_27b_nvfp4.ninfer \ --local-dir models

💡 已有 v2 旧版工件？无需重新下载，可参考 docs/weight-conversion.md 在本地一键升级。

🚀 启动本地 LLM API 服务：核心命令

下面是一条带投机解码与思考模式保留的完整启动命令，也是 docs/serving.md 中的官方示例：

./build/apps/ninfer-serve models/qwen3_8_27b_nvfp4.ninfer \ --host 127.0.0.1 \ --port 8080 \ --max-context 240000 \ --kv-capacity 240000 \ --max-concurrency 2 \ --kv-dtype fp8 \ --spec mtp --draft-tokens 3 \ --lm-head-draft \ --preserve-thinking

上图是官方示例集中的视觉测试图：本地 LLM 服务可以正确读出图中「NIFER VISION 731」、三个红圆与方位关系

关键参数速查

💡 视觉能力默认关闭（不占显存），需要处理图像/视频时务必加--vision；投机后端同理，不加--spec就不加载相关权重。运行./build/apps/ninfer-serve --help可查看完整参数说明。

✅ 验证服务状态与查看模型列表

服务启动后，两个轻量端点可以帮你确认本地 LLM 服务已就绪：

# 健康检查：返回 {"status":"ok"} 表示引擎可接受请求 curl http://127.0.0.1:8080/health # 查看对外模型名（即请求体中 model 字段应填的值） curl http://127.0.0.1:8080/v1/models

GET /v1/models会返回配置的模型别名与生效的max_model_len。若健康检查返回 503{"status":"unavailable"}，说明引擎整体已失败，需要重启服务。

💬 调用 OpenAI 兼容 API：curl 与 Python SDK

第一次请求：一分钟体验 Chat Completions

curl http://127.0.0.1:8080/v1/chat/completions \ -H 'Content-Type: application/json' \ -d '{ "model": "qwen3.8-27b", "messages": [ {"role": "system", "content": "Answer concisely."}, {"role": "user", "content": "What is speculative decoding?"} ], "max_tokens": 128 }'

思考过程会单独放在reasoning_content字段，最终回答保留在content字段，方便客户端分别渲染。

Python SDK 无缝切换

现有的 OpenAI SDK 代码只需要改两行——把base_url指向本地服务，api_key随便填（未设置--api-key时服务端不校验）：

from openai import OpenAI client = OpenAI(base_url="http://127.0.0.1:8080/v1", api_key="local-secret") response = client.responses.create( model="qwen3.8-27b", instructions="Answer concisely.", input="What is speculative decoding?", max_output_tokens=128, ) print(response.output_text)

除了/v1/chat/completions，NInfer 还实现了 OpenAI Responses Core（POST /v1/responses），支持 typed Items、previous_response_id多轮续接、SSE 语义事件流和store本地状态，详见 docs/serving.md 的 Responses 章节。

🧠 调用 Anthropic Messages API

Anthropic 客户端同样只需替换base_url。请求走/v1/messages端点：

curl http://127.0.0.1:8080/v1/messages \ -H 'Content-Type: application/json' \ -d '{ "model": "qwen3.8-27b", "max_tokens": 128, "messages": [ {"role": "user", "content": "Explain prefix reuse in one sentence."} ] }'

该端点支持完整的多轮历史（User/Assistant/System）、图像 block、Thinking 思考块、工具调用（tool-use）历史与 Anthropic SSE 流式协议；POST /v1/messages/count_tokens还能只数 token 不生成。

自然场景测试图：模型需识别邮箱号码 24、太阳位于画面右侧等视觉事实

🖼️ 开启多模态：让本地 LLM 服务看懂图片和视频

启动时加上--vision，即可通过image_url（HTTP 链接或 base64 data URI）发送图像，甚至通过video_url扩展字段发送视频：

curl http://127.0.0.1:8080/v1/chat/completions \ -H 'Content-Type: application/json' \ -d '{ "model": "qwen3.8-27b", "messages": [{ "role": "user", "content": [ {"type": "image_url", "image_url": {"url": "https://example.com/image.png"}}, {"type": "text", "text": "Describe this image."} ] }], "max_tokens": 128 }'

上面两张官方对比图（左图 2 圆、右图 3 圆加一颗黄星）用于验证多模态 LLM 服务的多图对比能力

⚠️ 注意：

• 未加--vision时，媒体请求会被拒绝并返回 HTTP 400vision_disabled
• 视觉请求当前还有一个 32,768 合并 token 的上限（取--max-context与该值的较小者）
• 相同媒体按 SHA-256 缓存，重复发送会自动复用预处理结果

仓库还内置了现成的多模态请求示例（examples/cli/messages/image_chart.json、examples/cli/messages/video_temporal.json 等），以及一个把 CLI 消息文件转发到运行中 Serve 端点的小工具 examples/cli/send_to_serve.py：

python3 -m examples.cli.send_to_serve \ examples/cli/messages/image_chart.json \ --base-url http://127.0.0.1:8080 \ --model qwen3.6-27b --no-thinking --max-tokens 64

🔐 安全加固：API Key 鉴权与跨域配置

本地 LLM 服务一旦要把--host改成0.0.0.0对外提供，务必先设置鉴权：

./build/apps/ninfer-serve models/qwen3_8_27b_nvfp4.ninfer --api-key local-secret

设置后，OpenAI 端点需要Authorization: Bearer local-secret，Anthropic 端点需要x-api-key: local-secret；GET /health保持免鉴权：

curl http://127.0.0.1:8080/v1/models -H 'Authorization: Bearer local-secret'

浏览器前端直连的场景可追加--cors开启宽松的 CORS 头（默认关闭）。

🛠️ 常见问题排查清单

更多运行行为细节（并发批次、前缀复用、请求日志--request-log-jsonl）见 docs/serving.md 的 "Execution behavior" 章节；单请求命令行用法见 docs/cli.md。

📚 延伸学习路径

• 完整 HTTP 服务文档（端点表、参数全表、流式协议）：docs/serving.md
• 命令行工具指南（文本/多模态输入、采样、MTP）：docs/cli.md
• 性能基准与测量方法：docs/performance.md
• 自定义模型权重转换：docs/weight-conversion.md
• 可离线运行的请求示例集：examples/cli/README.md

到这里，你就拥有一条命令启动、双协议兼容、支持思考与多模态的本地 LLM API 服务。试试把团队现有应用中指向云端的base_url换成本地http://127.0.0.1:8080/v1，感受单卡推理的性能与离线部署的自由吧！

【免费下载链接】ninferHigh-performance single-GPU inference for selected model checkpoints and GPUs.项目地址: https://gitcode.com/gh_mirrors/ni/ninfer