从 0 到 1 安装 TRAE：国内 / 国际版双流程指南

从 0 到 1 安装 TRAE：国内 / 国际版双流程指南（附避坑技巧）

TRAE（Tailored Rapid AI Engineering）是字节跳动开源的AI 驱动软件工程自动化工具，核心能力包括：基于架构图一键生成代码、智能上下文工程优化、生产环境 AI 服务运维调试、多工具链协作编排。无论是国内开发者还是海外用户，都能通过本文的双版本安装流程快速上手。

一、前置环境准备（国内 / 国际版通用）

在安装 TRAE 前，需确保你的环境满足以下要求：

二、国内版安装流程（适配国内网络）

国内用户推荐使用字节官方镜像源和Gitee 镜像仓库，避免网络超时问题。

方式 1：Docker Compose 一键部署（推荐）

步骤 1：克隆 Gitee 镜像仓库

# 克隆国内Gitee镜像（比GitHub快10倍） git clone https://gitee.com/bytedance/trae.git cd trae

步骤 2：配置国内镜像加速

修改docker-compose.yml中的镜像地址，替换为字节国内镜像：

# 原镜像（国际版） # image: bytebytego/trae-controller:latest # 替换为国内镜像 image: cr.bytedance.com/bytebytego/trae-controller:latest

同时配置 Docker 国内镜像加速器（以阿里云为例）：

1. 登录阿里云控制台 → 容器镜像服务 → 镜像加速器 → 获取专属加速地址
2. 修改 Docker 配置文件/etc/docker/daemon.json：

   { "registry-mirrors": ["https://你的阿里云加速地址.mirror.aliyuncs.com"] }

3. 重启 Docker 服务：

   sudo systemctl daemon-reload sudo systemctl restart docker

步骤 3：配置环境变量

复制.env.example为.env，并修改核心参数：

# 基础配置 TRAE_PORT=8000 TRAE_LOG_LEVEL=INFO # 向量数据库（国内用Milvus国内镜像） VECTOR_DB_TYPE=Milvus MILVUS_HOST=localhost MILVUS_PORT=19530 # 替换Milvus镜像为国内源 MILVUS_IMAGE=cr.bytedance.com/milvus/milvus:v2.4.0 # 大模型配置（国内可配置通义千问/文心一言API） OPENAI_API_KEY=你的通义千问API_KEY OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 # 通义千问兼容OpenAI接口

步骤 4：启动 TRAE 服务

# 后台启动并查看日志 docker compose up -d && docker compose logs -f

步骤 5：验证安装成功

等待 1-2 分钟（Milvus 初始化较慢），访问http://你的服务器IP:8000/docs，若显示OpenAPI 3.1.0 文档界面，则安装成功。

方式 2：本地源码部署（适合开发者定制）

步骤 1：克隆 Gitee 仓库并创建虚拟环境

git clone https://gitee.com/bytedance/trae.git cd trae # 创建虚拟环境 python3 -m venv venv source venv/bin/activate # Linux/macOS # .\venv\Scripts\Activate.ps1 # Windows

步骤 2：用国内 PyPI 镜像安装依赖

修改requirements.txt中的依赖源，或直接用清华镜像安装：

pip install --no-cache-dir -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

步骤 3：配置环境变量

同样复制.env.example为.env，并配置国内大模型 API 和向量数据库地址。

步骤 4：启动 TRAE 控制器

# 开发模式（代码修改自动重启） uvicorn trae.controller.main:app --host 0.0.0.0 --port 8000 --reload # 生产模式 gunicorn -w 4 -k uvicorn.workers.UvicornWorker trae.controller.main:app --bind 0.0.0.0:8000

三、国际版安装流程（适配海外网络）

国内用户直接vpn 后 浏览器搜索trae.ai即可，下载的时候可以先领取600次免费使用

海外用户直接使用GitHub 官方仓库和Docker Hub 镜像即可。

方式 1：Docker Compose 一键部署

步骤 1：克隆 GitHub 官方仓库

git clone https://github.com/bytedance/trae.git cd trae

步骤 2：配置环境变量

复制.env.example为.env，配置海外大模型 API 和向量数据库：

# 基础配置 TRAE_PORT=8000 TRAE_LOG_LEVEL=INFO # 向量数据库（用Docker Hub官方镜像） VECTOR_DB_TYPE=Milvus MILVUS_HOST=localhost MILVUS_PORT=19530 MILVUS_IMAGE=milvusdb/milvus:v2.4.0 # 大模型配置（用OpenAI/GPT-4） OPENAI_API_KEY=你的OpenAI_API_KEY OPENAI_BASE_URL=https://api.openai.com/v1

步骤 3：启动 TRAE 服务

docker compose up -d && docker compose logs -f

步骤 4：验证安装成功

访问http://你的服务器IP:8000/docs，显示 OpenAPI 文档即为成功。

方式 2：本地源码部署

步骤 1：克隆 GitHub 仓库并创建虚拟环境

git clone https://github.com/bytedance/trae.git cd trae python3 -m venv venv source venv/bin/activate

步骤 2：安装依赖

pip install --no-cache-dir -r requirements.txt

步骤 3：启动服务

uvicorn trae.controller.main:app --host 0.0.0.0 --port 8000 --reload

四、安装后快速验证：用 TRAE 生成第一个 RAG 系统

安装成功后，我们用 TRAE 的核心功能 ——基于架构图生成 RAG 系统来验证：

1. 访问http://你的服务器IP:8000/docs，找到POST /api/v1/code-generator/rag接口；
2. 上传以下 Mermaid 架构图（保存为rag_architecture.mmd）：

   graph TD A[用户] --> B[FastAPI接口层] B --> C[TRAE上下文工程] C --> D[Milvus向量检索] D --> E[OpenAI API调用] E --> B B --> F[PostgreSQL对话历史存储]

3. 配置参数：knowledge_base_name=product_docs、llm_api_key=你的大模型API_KEY；
4. 点击Execute，TRAE 会自动生成完整的 RAG 系统代码，下载后解压即可运行：

   unzip trae_generated_rag_system.zip cd trae_generated_rag_system pip install -r requirements.txt uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload

五、常见安装问题与避坑技巧

问题 1：Docker 拉取镜像超时

• 国内用户：配置阿里云 / 网易镜像加速器，或切换为字节国内镜像地址；
• 国际用户：检查网络是否能访问 Docker Hub，或用代理拉取镜像。

问题 2：CUDA 版本不匹配导致 GPU 无法识别

• 解决：安装与 CUDA 版本对应的 PyTorch 和 TRAE 依赖：

  # CUDA 11.8版本 pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

问题 3：TRAE 控制器启动失败，提示ModuleNotFoundError

• 解决：确保在虚拟环境中安装依赖，或检查 Python 版本是否为 3.11+。

问题 4：Milvus 向量数据库连接失败

• 解决：检查.env中的MILVUS_HOST和MILVUS_PORT是否正确，或重启 Milvus 容器：

  docker compose restart milvus-standalone

六、进阶配置：优化 TRAE 性能

1. GPU 加速配置

本地部署时，修改.env启用 GPU 加速：

# 启用GPU TRAE_GPU_ENABLED=true # 指定GPU设备（多GPU时用逗号分隔，如0,1） TRAE_GPU_DEVICES=0

2. 自定义大模型集成

除了 OpenAI / 通义千问，TRAE 还支持本地部署的大模型（如 LLaMA 3、Qwen）：

# 本地大模型配置 LLM_TYPE=local LOCAL_LLM_PATH=/path/to/llama3-7b-instruct LOCAL_LLM_FRAMEWORK=transformers

3. 日志与监控配置

修改.env配置日志级别和监控地址：

# 日志级别（DEBUG/INFO/WARNING/ERROR） TRAE_LOG_LEVEL=DEBUG # 监控地址（Prometheus） TRAE_METRICS_ENABLED=true TRAE_METRICS_PORT=9090

七、总结：TRAE 安装的核心原则

1. 国内优先用镜像：Gitee 仓库 + 字节镜像源 + 国内大模型 API，解决 90% 的网络问题；
2. Docker 优先于本地部署：一键式部署，避免环境依赖冲突；
3. GPU 加速是刚需：本地部署大模型时必须配置 GPU，否则推理速度慢到无法使用；
4. 验证先跑核心功能：安装后先测试 RAG 系统生成，确保核心功能正常。

TRAE 的核心价值在于降低 AI 应用的开发门槛—— 即使你不懂大模型底层逻辑，也能通过 TRAE 快速上线高质量的 AI 服务。现在就动手安装，体验 AI 驱动的软件工程自动化吧！