feat: add nexa-sdk
This commit is contained in:
Sun-ZhenXing
233
builds/nexa-sdk/README.zh.md
Normal file
233
builds/nexa-sdk/README.zh.md
Normal file
@@ -0,0 +1,233 @@
|
||||
# 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）
|
||||
|
||||
```bash
|
||||
# 复制环境配置文件
|
||||
cp .env.example .env
|
||||
|
||||
# 编辑 .env 配置模型和设置
|
||||
# NEXA_MODEL=gemma-2-2b-instruct
|
||||
|
||||
# 使用 CPU 配置文件启动服务
|
||||
docker compose --profile cpu up -d
|
||||
```
|
||||
|
||||
### GPU 加速使用
|
||||
|
||||
```bash
|
||||
# 复制环境配置文件
|
||||
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
|
||||
|
||||
```bash
|
||||
# 检查可用模型
|
||||
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` 更改模型：
|
||||
|
||||
```bash
|
||||
# 资源受限时使用小模型
|
||||
NEXA_MODEL=gemma-2-2b-instruct
|
||||
# 或
|
||||
NEXA_MODEL=qwen3-4b
|
||||
|
||||
# 追求更好质量时使用大模型
|
||||
NEXA_MODEL=llama-3-8b
|
||||
# 或
|
||||
NEXA_MODEL=mistral-7b
|
||||
```
|
||||
|
||||
### GPU 配置
|
||||
|
||||
对于 GPU 加速，调整层数：
|
||||
|
||||
```bash
|
||||
# 将所有层卸载到 GPU（最快）
|
||||
NEXA_GPU_LAYERS=-1
|
||||
|
||||
# 卸载 30 层（混合模式）
|
||||
NEXA_GPU_LAYERS=30
|
||||
|
||||
# 仅 CPU
|
||||
NEXA_GPU_LAYERS=0
|
||||
```
|
||||
|
||||
## 模型管理
|
||||
|
||||
模型会在首次运行时自动下载，并缓存在 `nexa_models` 卷中。容器内的默认缓存位置是 `/root/.cache/nexa`。
|
||||
|
||||
要使用不同的模型：
|
||||
|
||||
1. 在 `.env` 中更新 `NEXA_MODEL`
|
||||
2. 重启服务：`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）
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 内存不足
|
||||
|
||||
增加内存限制或使用更小的模型：
|
||||
|
||||
```bash
|
||||
NEXA_SDK_MEMORY_LIMIT=16G
|
||||
NEXA_SDK_MEMORY_RESERVATION=8G
|
||||
# 或切换到更小的模型
|
||||
NEXA_MODEL=gemma-2-2b-instruct
|
||||
```
|
||||
|
||||
### GPU 未检测到
|
||||
|
||||
确保已安装 NVIDIA Docker runtime：
|
||||
|
||||
```bash
|
||||
# 检查 GPU 可用性
|
||||
docker run --rm --gpus all nvidia/cuda:12.8.1-base-ubuntu22.04 nvidia-smi
|
||||
```
|
||||
|
||||
### 模型下载问题
|
||||
|
||||
如果访问私有模型，设置 HuggingFace 令牌：
|
||||
|
||||
```bash
|
||||
NEXA_HFTOKEN=your_hf_token_here
|
||||
```
|
||||
|
||||
### 性能缓慢
|
||||
|
||||
- 使用 GPU 配置文件以获得更好的性能
|
||||
- 增加 `NEXA_GPU_LAYERS` 以将更多计算卸载到 GPU
|
||||
- 分配更多资源或使用更小的模型
|
||||
|
||||
## 高级配置
|
||||
|
||||
### 自定义模型路径
|
||||
|
||||
如果要使用本地模型文件，将它们挂载为卷：
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
- ./models:/models
|
||||
- nexa_models:/root/.cache/nexa
|
||||
```
|
||||
|
||||
然后在命令中通过路径引用模型。
|
||||
|
||||
### HTTPS 配置
|
||||
|
||||
设置 HTTPS 的环境变量：
|
||||
|
||||
```bash
|
||||
NEXA_ENABLEHTTPS=true
|
||||
```
|
||||
|
||||
挂载证书文件：
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
- ./certs/cert.pem:/app/cert.pem:ro
|
||||
- ./certs/key.pem:/app/key.pem:ro
|
||||
```
|
||||
|
||||
## 健康检查
|
||||
|
||||
服务包含验证 API 是否响应的健康检查：
|
||||
|
||||
```bash
|
||||
curl http://localhost:8080/v1/models
|
||||
```
|
||||
|
||||
## 许可证
|
||||
|
||||
Nexa SDK 由 Nexa AI 开发。许可证信息请参考[官方仓库](https://github.com/NexaAI/nexa-sdk)。
|
||||
|
||||
## 链接
|
||||
|
||||
- [官方仓库](https://github.com/NexaAI/nexa-sdk)
|
||||
- [Nexa AI 网站](https://nexa.ai)
|
||||
- [文档](https://docs.nexa.ai)
|
||||
- [模型中心](https://sdk.nexa.ai)
|
||||
Reference in New Issue
Block a user