Qwen-Agent 安装部署指南

本文档提供 Qwen-Agent 在不同环境下的完整安装与部署方法，包括 Windows、Linux、Docker 等场景，并附带常见问题解决方案。

✅ 一、准备工作

1. 系统要求

• 操作系统：Windows（推荐 WSL 或 Anaconda）、Linux（Ubuntu 22.04+）、macOS
• Python 版本：≥ 3.8（推荐 3.10–3.12）
• 网络：能访问 GitHub、PyPI；如使用阿里云服务，需能访问 DashScope

💡 新手建议：先使用 阿里云 DashScope API，无需 GPU，5 分钟即可上手。

🚀 方案一：使用阿里云 DashScope（推荐新手）

步骤 1：获取 API Key

1. 访问 阿里云 DashScope 控制台
2. 开通服务 → 进入「API-KEY 管理」→ 创建新 Key
3. 保存好 API Key（关闭后无法再次查看）

步骤 2：安装 Qwen-Agent

# 创建虚拟环境（可选但推荐）
conda create -n qwen-agent python=3.10 -y
conda activate qwen-agent

# 安装 Qwen-Agent（含 RAG、代码解释器等）
pip install -U "qwen-agent[gui,rag,code_interpreter]"

步骤 3：配置并启动服务

创建 .env 文件（或直接在命令行中配置）：

API_KEY=你的_dashscope_api_key
MODEL_SERVER=dashscope
LLM_MODEL=qwen-plus
SERVER_HOST=0.0.0.0

启动 Web 服务：

python -m qwen_agent.gui.web_ui \
  --server_name 0.0.0.0 \
  --server_port 7864 \
  --model_server dashscope \
  --llm qwen-plus \
  --api_key 你的_api_key

✅ 访问 http://localhost:7864 即可使用图形界面！

💻 方案二：本地部署开源 Qwen 模型（需 GPU）

适用于拥有 NVIDIA GPU（建议 ≥16GB 显存）的用户

步骤 1：部署 Qwen 模型服务（OpenAI 兼容 API）

# 克隆 Qwen 仓库
git clone https://github.com/QwenLM/Qwen.git
cd Qwen

# 安装依赖
pip install -r requirements.txt
pip install fastapi uvicorn openai sse_starlette

# 启动模型服务（以 Qwen-7B-Chat-Int4 为例）
python openai_api.py \
  --server-name 0.0.0.0 \
  --server-port 7905 \
  -c Qwen/Qwen-7B-Chat-Int4

步骤 2：部署 Qwen-Agent 并连接本地模型

git clone https://github.com/QwenLM/Qwen-Agent.git
cd Qwen-Agent
pip install -e ."[gui,rag,code_interpreter]"

# 启动 Agent 服务
python run_server.py \
  --model_server http://127.0.0.1:7905/v1 \
  --workstation_port 7864 \
  --server_host 0.0.0.0

✅ 浏览器打开 http://localhost:7864 使用！

🐳 方案三：Docker 一键部署（推荐生产环境）

1. 安装 Docker

sudo apt update && sudo apt install -y docker.io docker-compose
sudo usermod -aG docker $USER  # 重启终端生效

2. 构建并运行容器

git clone https://gitcode.com/GitHub_Trending/qw/Qwen-Agent.git
cd Qwen-Agent

创建 .env 文件：

API_KEY=你的_dashscope_api_key
MODEL_SERVER=dashscope
LLM_MODEL=qwen-plus
SERVER_HOST=0.0.0.0

构建并运行：

docker build -t qwen-agent:latest .
docker run -d \
  --name qwen-agent \
  -p 7864:7864 \
  -p 7866:7866 \
  --env-file .env \
  -v $(pwd)/workspace:/app/workspace \
  qwen-agent:latest

✅ 访问 http://服务器IP:7864 即可！

🪟 Windows 安装常见问题：Rust / Cargo 报错

错误示例：

Cargo, the Rust package manager, is not installed or is not on PATH.
This package requires Rust and Cargo to compile extensions.

✅ 解决方案

1. 确认 Rust 已安装：运行 cargo --version
2. 将 Rust 加入系统 PATH：
   • 路径： %USERPROFILE%\.cargo\bin
   • 操作：控制面板 → 系统 → 高级系统设置 → 环境变量 → 用户变量 → Path → 新建 → 添加上述路径
3. 重启终端（PowerShell / CMD / VS Code）
4. 升级 pip 和构建工具：

   pip install --upgrade pip setuptools wheel

5. 尝试预编译包：

   pip install pydantic-core -i https://pypi.org/simple/

6. 或使用 Conda 安装（推荐）：

   conda install -c conda-forge pydantic-core

⚠️ 即使你在终端能运行 cargo，某些 Python 子进程仍可能找不到它。务必确保 PATH 在系统级别生效，并重启所有终端。

📊 部署方案对比

用户类型	推荐方案	所需资源
新手 / 无 GPU	DashScope 云端 API	能上网 + API Key
开发者 / 有 GPU	本地模型 + Qwen-Agent	NVIDIA GPU ≥8GB 显存
运维 / 生产环境	Docker 部署	Linux + Docker

🎁 提示：DashScope 提供免费额度，足够体验和小规模使用！

🔗 相关链接

• Qwen-Agent GitHub 仓库
• 阿里云 DashScope 控制台
• Rust 安装指南

---

文档更新时间：2026年2月28日 | 基于 Qwen-Agent 最新版本