# 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)