auto_agent/llm_server/README.md

LLM 推理服务

为 minor Agent 提供本地化推理后端，包含 6 个独立服务，均跑在 GPU 服务器上，通过 OpenAI 兼容 / 自定义 HTTP API 暴露。可整体部署，也可按需启用。

服务总览

服务	端口	模型	启动脚本	Python 服务端	关键端点
LLM	8900	Qwen3.6-35B-A3B-FP8	start_llm.sh	vLLM 内置	/v1/chat/completions
ASR	8901	Qwen3-ASR-1.7B	start_asr.sh	vLLM 内置	/v1/chat/completions
TTS	8902	VoxCPM 1.5 / 2	start_streaming_tts.sh	streaming_tts_server.py	/stream_tts
RAG	8903	Embedding-0.6B + Reranker-4B	start_rag_server.sh	rag_server.py	/embed /rerank
Image Gen	8904	Z-Image-Turbo	start_image_gen.sh	image_gen_server.py	/generate

所有脚本 / Python 文件均通过 os.path.dirname(__file__) 与 ${SCRIPT_DIR} 动态定位模型路径，目录整体迁移无需改代码。

---

一、部署流程

1. 上传到服务器

scp -P <SSH_PORT> -r Agent/llm_server/* <user>@<your-gpu-server>:~/llm_server/
ssh -o ServerAliveInterval=60 -o ServerAliveCountMax=3 -p <SSH_PORT> <user>@<your-gpu-server>

2. 服务器环境

cd ~/llm_server
chmod +x *.sh

# HuggingFace 镜像加速（国内必需）
export HF_ENDPOINT=https://hf-mirror.com
export HF_HUB_ENABLE_XET=0
echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.bashrc
echo 'export HF_HUB_ENABLE_XET=0' >> ~/.bashrc

python3 -m venv myenv && source myenv/bin/activate

# 一次性安装全部依赖
pip install vllm modelscope transformers fastapi uvicorn torch numpy torchaudio soundfile \
            bitsandbytes huggingface_hub voxcpm diffusers
sudo apt update && sudo apt install -y ffmpeg libavcodec-dev libavformat-dev libavutil-dev \
            libavdevice-dev libavfilter-dev libswscale-dev libswresample-dev

3. 下载模型

所有模型统一存放 ~/llm_server/models/：

模型	命令
Qwen3.6-35B-A3B-FP8 (LLM)	modelscope download --model Qwen/Qwen3.6-35B-A3B-FP8 --local_dir ./models/Qwen/Qwen3___6-35B-A3B-FP8
Qwen3-ASR-1.7B	modelscope download --model Qwen/Qwen3-ASR-1.7B --local_dir ./models/Qwen/Qwen3-ASR-1.7B
Qwen3-Embedding-0.6B	modelscope download --model Qwen/Qwen3-Embedding-0.6B --local_dir ./models/Qwen/Qwen3-Embedding-0___6B
Qwen3-Reranker-4B	modelscope download --model Qwen/Qwen3-Reranker-4B --local_dir ./models/Qwen/Qwen3-Reranker-4B
VoxCPM 1.5 (推荐)	modelscope download --model OpenBMB/VoxCPM1.5 --local_dir ./models/VoxCPM1__5
VoxCPM 2 (音质更佳)	modelscope download --model OpenBMB/VoxCPM2 --local_dir ./models/VoxCPM2
Z-Image-Turbo	modelscope download --model Tongyi-MAI/Z-Image-Turbo --local_dir ./models/Tongyi-MAI/Z-Image-Turbo

完成后目录结构：

~/llm_server/models/
├── Qwen/
│   ├── Qwen3___6-35B-A3B-FP8/      # LLM
│   ├── Qwen3-ASR-1.7B/             # ASR
│   ├── Qwen3-Embedding-0___6B/     # Embedding
│   └── Qwen3-Reranker-4B/          # Reranker
├── VoxCPM1__5/                     # TTS
└── Tongyi-MAI/Z-Image-Turbo/       # Image Gen

---

二、启动与测试

每个服务独立启动，互不依赖。所有 start_*.sh 支持环境变量覆盖：

环境变量	作用	适用脚本
HOST_PORT	服务端口	全部
LOCAL_MODEL_DIR / MODEL_PATH / VOXCPM_MODEL_PATH	模型目录	全部
CUDA_VISIBLE_DEVICES	GPU 设备号	全部
SPECIFIC_GPU	单 GPU 指定（写 CUDA_VISIBLE_DEVICES）	image_gen / tts
SERVER_API_KEY	API Key 鉴权（空=不校验，任意值放行）	全部
SERVER_MODELNAME	服务模型名（请求 body.model 须匹配；空=不校验）	全部

鉴权与模型名校验：SERVER_API_KEY 为空时服务不校验 API Key（任意值放行）； SERVER_MODELNAME 为空时服务不校验请求中的 model 字段。 部署时如需启用，示例：

SERVER_API_KEY=sk-xxx SERVER_MODELNAME=Qwen3-ASR-1.7B bash start_asr.sh

LLM · 8900

bash start_llm.sh
# 启用鉴权与自定义模型名
# SERVER_API_KEY=sk-xxx SERVER_MODELNAME=Qwen/Qwen3.6-35B-A3B-FP8 bash start_llm.sh
# 测试
python3 test_llm.py --url http://127.0.0.1:8900            # 非流式
python3 test_llm.py --url http://127.0.0.1:8900 --stream   # 流式

vLLM 加载 Qwen3.6-35B-A3B-FP8，OpenAI 兼容 API，使用 chat_template.jinja 格式化对话。 --served-model-name 由 SERVER_MODELNAME 控制（默认 Qwen/Qwen3.6-35B-A3B-FP8）； SERVER_API_KEY 非空时传给 vLLM --api-key，请求需携带 Authorization: Bearer <key>。

ASR · 8901

bash start_asr.sh
# 启用鉴权与自定义模型名
# SERVER_API_KEY=sk-xxx SERVER_MODELNAME=Qwen3-ASR-1.7B bash start_asr.sh
# 测试
python3 test_asr.py --audio /path/to/audio.wav --url http://127.0.0.1:8901/v1/chat/completions

vLLM 加载 Qwen3-ASR-1.7B，--served-model-name 由 SERVER_MODELNAME 控制（默认 Qwen3-ASR-1.7B）。

TTS · 8902（流式）

bash start_streaming_tts.sh
# 启用鉴权与自定义模型名
# SERVER_API_KEY=sk-xxx SERVER_MODELNAME=VoxCPM1.5 bash start_streaming_tts.sh
# 测试（流式返回 wav 分块）
curl -X POST http://127.0.0.1:8902/stream_tts \
  -H "Content-Type: application/json" \
  -d '{"model": "VoxCPM1.5", "text": "你好，这是一个流式语音合成测试。", "request_id": "test-1"}'

VoxCPM 流式合成，边生成边返回 wav chunk，配合 reference_audio.wav 控制音色。 配置了 SERVER_MODELNAME 时请求 body 须带 model 字段；配置了 SERVER_API_KEY 时须带 Authorization: Bearer <key> 头。

RAG · 8903（Embedding + Reranker）

bash start_rag_server.sh
# 启用鉴权与自定义模型名
# SERVER_API_KEY=sk-xxx SERVER_MODELNAME=Qwen3-Embedding-0.6B bash start_rag_server.sh
python3 test_rag.py

Image Gen · 8904

LOCAL_MODEL_DIR=./models/Tongyi-MAI/Z-Image-Turbo SPECIFIC_GPU=3 bash start_image_gen.sh
# 启用鉴权与自定义模型名
# SERVER_API_KEY=sk-xxx SERVER_MODELNAME=Z-Image-Turbo bash start_image_gen.sh
# 测试
curl -X POST http://127.0.0.1:8904/generate \
  -H "Content-Type: application/json" \
  -d '{"model": "Z-Image-Turbo", "prompt": "一只橘猫坐在窗台上，阳光洒落", "width": 1024, "height": 1024, "return_format": "base64"}' \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print(f'成功:{d.get(\"success\")} 尺寸:{d.get(\"width\")}x{d.get(\"height\")} 耗时:{d.get(\"elapsed_seconds\",\"?\")}s')"

Z-Image-Turbo 基于 Diffusers，9 步推理生成 1024×1024 图片，return_format=base64 直接返回内联数据。

---

三、本地端口映射（开发调试）

将远程端口映射到本地，用 http://localhost:8900 直连远程服务：

# 一次性映射全部端口
ssh -fN -o ServerAliveInterval=60 -o ServerAliveCountMax=3 \
  -L 8900:0.0.0.0:8900 -L 8901:0.0.0.0:8901 -L 8902:0.0.0.0:8902 \
  -L 8903:0.0.0.0:8903 -L 8904:0.0.0.0:8904 \
  <user>@<your-gpu-server> -p <SSH_PORT>

验证映射（HTTP 200 即通）：

for p in 8900 8901 8902 8903 8904; do
  curl -o /dev/null -s -w "$p: %{http_code}\n" http://localhost:$p/health
done

---

四、停止服务

for p in 8900 8901 8902 8903 8904; do kill $(lsof -t -i:$p); done

---

五、接入 Agent

四个本地服务（ASR / TTS / RAG / ImageGen）在 Agent 的 env_config.json models 列表中注册（设置 → 环境变量 → LLM 模型列表，或直接编辑 src/agent/config/env_config.json），base_url 指向本地映射端口，api_key 留空（对应服务端未启用鉴权）。Agent 运行时按 model 字段匹配取得服务地址：

Agent 能力	模型列表条目	字段示例
语音识别	name: "ASR 语音识别"	model: "Qwen3-ASR-1.7B", base_url: "http://localhost:8901", api_key: ""
语音合成	name: "TTS 语音合成"	model: "VoxCPM1.5", base_url: "http://localhost:8902", api_key: ""
知识库检索	name: "RAG 检索"	model: "Qwen3-Embedding-0.6B", base_url: "http://localhost:8903", api_key: ""
图像生成	name: "图像生成"	model: "Z-Image-Turbo", base_url: "http://localhost:8904", api_key: ""

💡 若服务端部署时设置了 SERVER_API_KEY / SERVER_MODELNAME，请把模型条目中的 api_key 与 model 改成与之一致，Agent 发出的请求会携带 Authorization: Bearer <api_key> 与 model 字段。

💡 不必自建本服务，Agent 也支持任何 OpenAI 兼容 API（云端 Qwen / DeepSeek / OpenAI 等），填入 base_url + api_key 即可。