Neroued/ninfer - 快速上手

由于 trendforge.devlive.top 访问受限，请切换到 trendforge.devlive.org 域名

项目介绍快速开始学习路径贡献者 3 增长趋势 Commit 历史代码统计生态关系项目时间线项目竞品上榜历史

NInfer 5分钟快速开始

在单GPU上快速部署并运行Qwen3.8-27B NVFP4模型的高性能推理。

环境要求

支持的操作系统

Linux

运行环境

CUDA Toolkit 13.1 必需

所需工具

NVIDIA GeForce RTX 5090

必需的GPU硬件

必需

CMake

构建系统

必需

Ninja

构建工具

必需

pkg-config

库依赖管理

必需

FFmpeg开发库

多媒体处理 (libavformat, libavcodec, libavutil, libswscale)

必需

libcurl

网络请求

必需

操作步骤

构建项目

克隆仓库并使用CMake构建推理引擎的可执行文件。

克隆项目代码

git clone https://github.com/Neroued/ninfer.git

进入项目目录

cd ninfer

配置Release构建预设

cmake --preset release

编译项目

cmake --build build/ -j $(nproc)

预期结果：：构建完成后，在 `build/` 目录下生成 `ninfer` 可执行文件。

确保已安装所有系统依赖，特别是CUDA 13.1和FFmpeg开发库。

下载模型

使用Hugging Face CLI下载官方提供的快速开始模型权重。

安装Hugging Face CLI（如果尚未安装）

pip install huggingface_hub[cli]

下载Qwen3.8-27B NVFP4模型

huggingface-cli download Neroued/ninfer qwen3827bnvfp4.ninfer --local-dir ./models

预期结果：：模型文件 `qwen3827bnvfp4.ninfer` 被下载到 `./models` 目录。

下载约需几分钟，取决于网络速度。此模型为官方优化后的NVFP4格式。

启动推理服务并发送测试请求

启动一个兼容OpenAI API的服务，并发送一个简单的文本请求进行测试。

在后台启动推理服务，支持2路并发和投机解码

./build/ninfer serve --model ./models/qwen3827bnvfp4.ninfer --concurrency 2 --spec on &

发送一个OpenAI格式的聊天请求

curl http://localhost:8080/v1/chat/completions -H 'Content-Type: application/json' -d '{"model": "qwen3.8-27b", "messages": [{"role": "user", "content": "Hello, what is 1+1?"}]}'

预期结果：：服务启动后会在终端显示 `Engine-ready` 等信息。Curl命令将返回一个包含AI回复的JSON响应，其中 `choices[0].message.content` 字段包含模型的回答。

服务默认监听8080端口。如果端口冲突，可以通过 `--port` 参数指定其他端口。

运行一次CLI查询

使用命令行工具直接运行一个一次性查询。

执行一次CLI推理

./build/ninfer run --model ./models/qwen3827bnvfp4.ninfer --prompt "Explain quantum computing in one sentence." --max-tokens 100

预期结果：：在终端的标准输出(stdout)中直接打印出模型的回复文本。标准错误(stderr)会显示推理性能报告。

使用 `--vision` 参数可以处理图像或视频输入。

验证运行成功

通过以下标志确认环境已正确配置且模型能正常运行。

构建步骤生成了 `build/ninfer` 可执行文件

模型文件 `qwen3827bnvfp4.ninfer` 存在于 `./models` 目录

启动服务后终端显示 `Engine-ready` 等引擎就绪信息

curl命令返回了包含AI回答的JSON响应

CLI查询在标准输出中打印出了回答文本

快速提示

使用

所有运行命令都应在项目根目录下执行，以确保相对路径正确。

性能

首次运行时，模型权重加载可能需要数十秒到一分钟，取决于系统性能。

调试

使用 `--log-level debug` 参数可以获取更详细的启动和运行日志，用于调试。

架构

NInfer针对单GPU优化，无需配置复杂的分布式设置。

常见问题

构建时CMake报错，找不到CUDA或sm120a架构。

确保已安装支持sm120a（即RTX 5090）的CUDA 13.1 Toolkit，并且CMake版本不低于3.28。

运行时报告缺少libavcodec等FFmpeg库。

安装FFmpeg的开发包，例如在Ubuntu上：`sudo apt install libavformat-dev libavcodec-dev libavutil-dev libswscale-dev`

Hugging Face下载失败或很慢。

检查网络连接，或尝试设置HF镜像。确保已安装`huggingface_hub[cli]`。

服务启动后curl请求超时或连接被拒绝。

检查服务是否已成功启动（查看终端输出）。确认端口未被防火墙阻止或已被其他进程占用。

推理速度明显低于性能基准表中的数据。

确认使用的是正确的GPU（RTX 5090），并且已安装最新的NVIDIA驱动和CUDA 13.1。检查系统是否有其他进程占用大量GPU资源。

下一步

尝试更多模型

下载README中列出的其他官方模型（如Qwen3.6-27B或MoE模型）进行体验。

探索多模态推理

使用 `--vision` 参数和 `--messages` 参数，尝试向模型输入图像或视频。

配置高级功能

查阅项目文档，了解如何调整并发数、KV缓存大小、投机解码策略等参数以优化性能。

查看性能数据

阅读README中的性能章节，了解在不同场景下的吞吐量和延迟指标。