alexsun/compose-anything

Fork 0

Files

Sun-ZhenXing 1c42cb2800 feat: add nexa-sdk

2025-11-16 00:12:14 +08:00

6.2 KiB

Raw Blame History

Nexa SDK

Nexa SDK 是一个功能全面的本地 AI 模型运行工具包。它支持多种模型类型的推理，包括 LLM、VLM（视觉语言模型）、TTS（文本转语音）、ASR（自动语音识别）等。该工具专注于性能优化，支持 CPU 和 GPU 加速。

特性

多模型支持：运行 LLM、VLM、TTS、ASR、嵌入、重排序和图像生成模型
OpenAI 兼容 API：提供标准的 OpenAI API 端点，便于集成
GPU 加速：通过 NVIDIA CUDA 提供可选的 GPU 支持，实现更快的推理速度
资源管理：可配置的 CPU/内存限制和 GPU 层卸载
模型缓存：持久化模型存储，加快启动速度
配置文件支持：轻松在 CPU 模式和 GPU 加速模式之间切换

快速开始

前置要求

Docker 和 Docker Compose
GPU 支持需要：NVIDIA Docker runtime 和兼容的 GPU

基本使用（CPU）

# 复制环境配置文件
cp .env.example .env

# 编辑 .env 配置模型和设置
# NEXA_MODEL=gemma-2-2b-instruct

# 使用 CPU 配置文件启动服务
docker compose --profile cpu up -d

GPU 加速使用

# 复制环境配置文件
cp .env.example .env

# 配置 GPU 使用
# NEXA_MODEL=gemma-2-2b-instruct
# NEXA_GPU_LAYERS=-1  # -1 表示所有层都在 GPU 上

# 使用 GPU 配置文件启动服务
docker compose --profile gpu up -d

配置

环境变量

变量	默认值	说明
`NEXA_SDK_VERSION`	`latest`	Nexa SDK Docker 镜像版本
`NEXA_SDK_PORT_OVERRIDE`	`8080`	API 访问的主机端口
`NEXA_MODEL`	`gemma-2-2b-instruct`	要加载的模型（如 qwen3-4b、llama-3-8b、mistral-7b）
`NEXA_HOST`	`0.0.0.0:8080`	服务器绑定地址
`NEXA_KEEPALIVE`	`300`	模型保活超时时间（秒）
`NEXA_ORIGINS`	`*`	CORS 允许的源
`NEXA_HFTOKEN`	-	用于私有模型的 HuggingFace 令牌
`NEXA_LOG`	`none`	日志级别（none、debug、info、warn、error）
`NEXA_GPU_LAYERS`	`-1`	卸载到 GPU 的层数（-1 = 全部，0 = 仅 CPU）
`NEXA_SHM_SIZE`	`2g`	共享内存大小
`TZ`	`UTC`	容器时区

资源限制

变量	默认值	说明
`NEXA_SDK_CPU_LIMIT`	`4.0`	最大 CPU 核心数
`NEXA_SDK_MEMORY_LIMIT`	`8G`	最大内存
`NEXA_SDK_CPU_RESERVATION`	`2.0`	预留 CPU 核心数
`NEXA_SDK_MEMORY_RESERVATION`	`4G`	预留内存

配置文件

cpu：使用 CPU 推理运行（需要指定默认配置文件）
gpu：使用 GPU 加速运行（需要 NVIDIA GPU）

使用示例

测试 API

# 检查可用模型
curl http://localhost:8080/v1/models

# 聊天完成
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma-2-2b-instruct",
    "messages": [
      {"role": "user", "content": "你好！"}
    ]
  }'

使用不同的模型

编辑 .env 更改模型：

# 资源受限时使用小模型
NEXA_MODEL=gemma-2-2b-instruct
# 或
NEXA_MODEL=qwen3-4b

# 追求更好质量时使用大模型
NEXA_MODEL=llama-3-8b
# 或
NEXA_MODEL=mistral-7b

GPU 配置

对于 GPU 加速，调整层数：

# 将所有层卸载到 GPU（最快）
NEXA_GPU_LAYERS=-1

# 卸载 30 层（混合模式）
NEXA_GPU_LAYERS=30

# 仅 CPU
NEXA_GPU_LAYERS=0

模型管理

模型会在首次运行时自动下载，并缓存在 nexa_models 卷中。容器内的默认缓存位置是 /root/.cache/nexa。

要使用不同的模型：

在 .env 中更新 NEXA_MODEL
重启服务：docker compose --profile <cpu|gpu> restart

API 端点

Nexa SDK 提供 OpenAI 兼容的 API 端点：

GET /v1/models - 列出可用模型
POST /v1/chat/completions - 聊天完成
POST /v1/completions - 文本完成
POST /v1/embeddings - 文本嵌入
GET /health - 健康检查
GET /docs - API 文档（Swagger UI）

故障排除

内存不足

增加内存限制或使用更小的模型：

NEXA_SDK_MEMORY_LIMIT=16G
NEXA_SDK_MEMORY_RESERVATION=8G
# 或切换到更小的模型
NEXA_MODEL=gemma-2-2b-instruct

GPU 未检测到

确保已安装 NVIDIA Docker runtime：

# 检查 GPU 可用性
docker run --rm --gpus all nvidia/cuda:12.8.1-base-ubuntu22.04 nvidia-smi

模型下载问题

如果访问私有模型，设置 HuggingFace 令牌：

NEXA_HFTOKEN=your_hf_token_here

性能缓慢

使用 GPU 配置文件以获得更好的性能
增加 NEXA_GPU_LAYERS 以将更多计算卸载到 GPU
分配更多资源或使用更小的模型

高级配置

自定义模型路径

如果要使用本地模型文件，将它们挂载为卷：

volumes:
  - ./models:/models
  - nexa_models:/root/.cache/nexa

然后在命令中通过路径引用模型。

HTTPS 配置

设置 HTTPS 的环境变量：

NEXA_ENABLEHTTPS=true

挂载证书文件：

volumes:
  - ./certs/cert.pem:/app/cert.pem:ro
  - ./certs/key.pem:/app/key.pem:ro

健康检查

服务包含验证 API 是否响应的健康检查：

curl http://localhost:8080/v1/models

许可证

Nexa SDK 由 Nexa AI 开发。许可证信息请参考官方仓库。

6.2 KiB Raw Blame History Unescape Escape