# anythingllm_desktop_deploy

**Repository Path**: sambios/anythingllm_desktop_deploy

## Basic Information

- **Project Name**: anythingllm_desktop_deploy
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-11-07
- **Last Updated**: 2025-11-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AnythingLLM Desktop 部署指南

## 项目简介

本项目提供了基于 Docker 的 AnythingLLM 桌面版部署方案，集成了 Qwen3-30B-A3B-Instruct-AWQ 模型，使用 vLLM 作为推理后端，支持 GCU 硬件加速。

## 系统要求

### 硬件要求
- **GCU 设备**: 至少 1 个 GCU 设备（推荐 4 个用于张量并行）
- **内存**: 建议 32GB 以上
- **存储**: 至少 100GB 可用空间（用于模型存储）

### 软件要求
- **操作系统**: Linux (推荐 Ubuntu 20.04/22.04)
- **Docker**: 版本 20.10 或更高
- **Docker Compose**: 版本 2.0 或更高
- **驱动**: GCU 驱动已正确安装

## 目录结构

```
anythingllm_desktop_deploy/
├── docker-compose.yaml       # Docker Compose 配置文件
├── install.sh                # AnythingLLM 安装脚本
├── anythingllm/
│   └── start_vllm_server.sh  # vLLM 服务启动脚本
└── README.md                 # 本文档
```

## 部署步骤

### 1. 准备模型文件

确保 Qwen3-30B-A3B-Instruct-AWQ 模型已下载到主机的 `/data/models` 目录：

```bash
# 检查模型目录
ls -la /data/models/Qwen3-30B-A3B-Instruct-AWQ
```

如果模型不存在，请先下载模型文件到该目录。

### 2. 配置环境变量

编辑 `docker-compose.yaml` 文件，根据实际情况调整以下参数：

```yaml
environment:
  - MODEL_NAME=Qwen3-30B-A3B-Instruct-AWQ  # 模型名称
  - TP=4                                    # 张量并行度（根据 GCU 数量调整）
  - VISIBLE_DEVICE=0                        # 可见设备 ID
  - PORT=3020                               # 服务端口
```

**参数说明**:
- `MODEL_NAME`: 模型目录名称，需与 `/data/models` 下的实际目录名一致
- `TP`: 张量并行度，建议设置为可用 GCU 设备数量
- `VISIBLE_DEVICE`: GCU 设备 ID，多个设备用逗号分隔（如 `0,1,2,3`）
- `PORT`: vLLM API 服务监听端口

### 3. 启动服务

使用 Docker Compose 启动服务：

```bash
# 进入项目目录
cd /root/clients/main/anythingllm_desktop_deploy

# 启动服务（后台运行）
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看服务日志
docker-compose logs -f
```

### 4. 验证部署

等待服务启动完成（通常需要 1-3 分钟），然后验证 API 是否正常：

```bash
# 检查健康状态
curl http://localhost:3020/health

# 查看模型列表
curl http://localhost:3020/v1/models

# 测试推理接口
curl http://localhost:3020/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen3-30B-A3B-Instruct-AWQ",
    "prompt": "你好，请介绍一下你自己。",
    "max_tokens": 100,
    "temperature": 0.7
  }'
```

### 5. 安装 AnythingLLM Desktop（可选）

如果需要安装 AnythingLLM 桌面客户端：

```bash
# 运行安装脚本
bash install.sh
```

该脚本会自动下载并安装 AnythingLLM 桌面应用。

## 服务管理

### 启动服务
```bash
docker-compose up -d
```

### 停止服务
```bash
docker-compose down
```

### 重启服务
```bash
docker-compose restart
```

### 查看日志
```bash
# 实时查看日志
docker-compose logs -f

# 查看最近 100 行日志
docker-compose logs --tail=100
```

### 进入容器
```bash
docker exec -it qwen3-30b-a3b_backend bash
```

## vLLM 配置说明

`start_vllm_server.sh` 脚本中的关键参数：

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--model` | 模型路径 | `/home/models/${MODEL_NAME}` |
| `--gpu-memory-utilization` | GPU 内存利用率 | 0.9 |
| `--max-model-len` | 最大序列长度 | 8192 |
| `--port` | 服务端口 | 3010 |
| `--block-size` | KV Cache 块大小 | 64 |
| `--device` | 设备类型 | gcu |
| `--tensor-parallel-size` | 张量并行度 | ${TP} |
| `--quantization` | 量化方法 | moe_wna16_gcu |
| `--enable_prefix_caching` | 启用前缀缓存 | 是 |

## 故障排查

### 服务无法启动

1. **检查 GCU 驱动**
   ```bash
   # 检查 GCU 设备
   ls -la /dev/gcu*
   ```

2. **检查模型路径**
   ```bash
   # 确认模型文件存在
   ls -la /data/models/Qwen3-30B-A3B-Instruct-AWQ
   ```

3. **查看容器日志**
   ```bash
   docker-compose logs
   ```

### 内存不足

如果遇到 OOM (Out of Memory) 错误：

1. 降低 `--gpu-memory-utilization` 参数（如改为 0.8）
2. 减少 `--max-model-len` 参数（如改为 4096）
3. 减少 `--tensor-parallel-size` 参数

### 端口冲突

如果端口 3020 已被占用：

1. 修改 `docker-compose.yaml` 中的 `PORT` 环境变量
2. 修改端口映射配置 `ports` 部分

### 性能问题

1. **增加张量并行度**: 如果有多个 GCU，增加 `TP` 参数
2. **启用前缀缓存**: 已默认启用 `--enable_prefix_caching`
3. **调整批处理大小**: 可在 vLLM 参数中添加 `--max-num-seqs`

## API 使用示例

### Chat Completions API

```bash
curl http://localhost:3020/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen3-30B-A3B-Instruct-AWQ",
    "messages": [
      {"role": "system", "content": "你是一个有帮助的AI助手。"},
      {"role": "user", "content": "什么是人工智能？"}
    ],
    "temperature": 0.7,
    "max_tokens": 500
  }'
```

### Completions API

```bash
curl http://localhost:3020/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen3-30B-A3B-Instruct-AWQ",
    "prompt": "人工智能的定义是",
    "max_tokens": 200,
    "temperature": 0.7,
    "top_p": 0.9
  }'
```

## 性能优化建议

1. **使用多 GCU**: 设置合适的 `TP` 值以充分利用多个 GCU 设备
2. **调整内存利用率**: 根据实际负载调整 `--gpu-memory-utilization`
3. **启用前缀缓存**: 对于相似的请求可以显著提升性能（已默认启用）
4. **使用量化模型**: 当前使用 AWQ 量化，在保持精度的同时减少内存占用
5. **调整并发数**: 通过 `--max-num-seqs` 参数控制最大并发请求数

## 安全建议

1. **网络隔离**: 生产环境建议使用防火墙限制访问
2. **API 认证**: 考虑在前端添加认证层
3. **资源限制**: 使用 Docker 的资源限制功能防止资源耗尽
4. **日志监控**: 定期检查日志，监控异常行为

## 更新与维护

### 更新模型

1. 下载新模型到 `/data/models` 目录
2. 修改 `docker-compose.yaml` 中的 `MODEL_NAME`
3. 重启服务: `docker-compose restart`

### 更新镜像

```bash
# 拉取最新镜像
docker pull all_in_one_arm_image_v1_1_0_6:v1

# 重新创建容器
docker-compose up -d --force-recreate
```

## 技术支持

如遇到问题，请提供以下信息：

1. 系统信息: `uname -a`
2. Docker 版本: `docker --version`
3. 容器日志: `docker-compose logs`
4. GCU 设备信息: `ls -la /dev/gcu*`

## 许可证

请参考相关组件的许可证：
- vLLM: Apache 2.0
- Qwen3 模型: 参考通义千问模型许可协议
- AnythingLLM: MIT License

---

**最后更新**: 2025-11-07