适用场景
这套方案适合两类人：一是手里已经有若干 prompt 或 Agent 工作流，但每次迭代都靠"改一版、手动跑几遍、凭感觉判断好坏"的团队；二是想给智能体搭一个可以反复试错、自动打分、按分数筛选并生成下一代的闭环环境的人。AgentGarten 的核心思路很朴素：把"智能体—任务—评分—变异—再试"这条链路做成一个持续运行的实时试炼场，让智能体在对抗和反馈里自己往前走，而不是靠人一次次手改。
下面从零开始把试炼场跑起来，接上模型、注册智能体、设计试炼任务、启动进化、看结果。
> 说明：AgentGarten 的配置字段、CLI 子命令、镜像名会随版本调整。本文重点在流程与排查思路，凡是涉及具体版本、仓库地址、镜像 tag 的地方，都以官方文档和 --help 输出为准。命令里的子命令形态如果不一致，用 agentgarten --help 逐层找即可。
环境与前置条件
操作系统：Linux 服务器优先（主流 LTS 发行版均可），macOS 也能跑通，Windows 建议走 WSL2。
运行时：
- Docker Engine + Docker Compose v2（版本以官方文档当前版本为准）
- Python 3.10 以上，建议用虚拟环境
- 如果用官方前端单独部署，还需要一个较新的 Node.js LTS
硬件建议：
- 纯调用云端模型 API：4 核 8GB 内存起步，16GB 更稳（试炼场 + 数据库 + 队列一起跑）
- 磁盘：至少 20GB 可用，试炼记录、日志、快照都会写盘，长期跑建议 50GB 以上并配日志轮转
- 本地跑模型：显存按所选模型的实际需求准备，7B 级别量化后通常需要 8GB 以上显存；显存不够就切 API 模式
其他：
- 一个 OpenAI 兼容的模型接口（base_url + api_key + 模型名）
- 能访问容器镜像仓库和模型端点
- 给试炼场分配一个固定端口，别和现有服务冲突
分步骤部署
第 1 步：拉取代码，先看目录结构
```bash
git clone <AgentGarten 官方仓库地址> agentgarten
cd agentgarten
ls
```
仓库地址以官方文档为准。拉下来之后先别急着 up，花两分钟看目录：通常会有 docker-compose.yml、.env.example、agents/（智能体定义）、trials/（试炼任务）、evolution/（进化策略）这几块。看清哪块放什么，后面配置就不会乱。
第 2 步：准备环境变量
```bash
cp .env.example .env
```
然后编辑 .env，填上这几类值：
```bash
试炼场对外端口
ARENA_PORT=8080
数据库与队列
PG_PASSWORD=change-me-please
DATABASE_URL=postgresql://agentgarten:change-me-please@db:5432/agentgarten
REDIS_URL=redis://cache:6379/0
模型接入（OpenAI 兼容端点）
LLM_BASE_URL=https://your-llm-endpoint/v1
LLM_API_KEY=sk-xxxxxxxxxxxxxxxx
LLM_MODEL=your-model-name
试炼场 API 鉴权
ARENA_API_TOKEN=change-me-too
```
三个要点：数据库密码和 API AI 词典：Token">Token 一定要改掉，别用示例值直接上公网；LLM_BASE_URL 记得带 /v1 这类路径后缀，很多人在这里踩坑；模型名要写接口实际接受的那个字符串。
第 3 步：先做一次配置检查，再启动
```bash
docker compose config
```
这条命令会把变量替换后的最终配置打印出来，成功的话你会看到完整的 YAML，没有 variable is not set 之类的警告。确认无误再启动：
```bash
docker compose up -d
docker compose ps
```
docker compose ps 里所有服务状态应该是 running 或 healthy。如果有服务反复重启，先跳到最后一节看报错排查。
第 4 步：确认试炼场活着
打开浏览器访问 http://<服务器IP>:8080，应该能看到试炼场控制台。如果是纯命令行环境，用健康检查接口验证：
```bash
curl -s http://localhost:8080/healthz
```
返回类似 {"status":"ok"} 的 JSON 就算通了。具体路径以官方文档为准，常见的是 /healthz 或 /api/health。
第 5 步：接入模型
进入控制台的模型/Provider 设置页，新增一个 OpenAI 兼容供应商，把 .env 里的 LLM_BASE_URL、LLM_API_KEY、LLM_MODEL 填进去，然后点"测试连接"。
也可以走 CLI：
```bash
docker compose exec arena agentgarten provider add \
--name default \
--base-url "$LLM_BASE_URL" \
--api-key "$LLM_API_KEY" \
--model "$LLM_MODEL"
docker compose exec arena agentgarten provider test --name default
```
测试成功的标志是会返回一段正常的模型回复，而不是超时或 401。
第 6 步：注册第一个智能体
在 agents/ 下新建一个 YAML，比如 agents/price-hunter.yaml：
```yaml
id: price-hunter
name: 比价小助手
provider: default
model:
temperature: 0.7
prompt:
system: |
你是一名电商比价助手。用户会给出一个商品名和一组候选报价，
你要在预算约束内选出性价比最高的选项，并用三句话说明理由。
如果没有任何选项满足预算，直接回答"无合适选项"。
memory:
type: window
size: 8
tools:
- name: search_catalog
description: 按关键词检索商品目录，返回候选商品与价格
limits:
max_tokens_per_turn: 800
timeout_seconds: 30
```
注册并确认：
```bash
docker compose exec arena agentgarten agent apply -f agents/price-hunter.yaml
docker compose exec arena agentgarten agent list
```
agent list 里能看到 price-hunter 就成功了。
第 7 步：设计试炼任务与评分器
试炼任务的关键是评分规则要能被机器算出来，否则进化就没有方向。在 trials/ 下新建 trials/budget-pick.yaml：
```yaml
id: budget-pick
name: 预算内选品
rounds: 20
turns_per_round: 6
dataset:
path: data/products.csv
input_field: query
expected_field: best_option
scorers:
- type: rule
name: 预算合规
weight: 0.3
- type: exact_match
name: 选项正确
weight: 0.3
- type: llm_judge
name: 理由质量
weight: 0.4
model: ${LLM_MODEL}
rubric: |
1 分：理由与选项一致，但空洞
3 分：理由提到价格与需求匹配
5 分：理由指出关键权衡，并说明为何排除其他候选
limits:
max_tokens_per_round: 20000
timeout_seconds: 120
```
三条经验：权重加起来是 1；规则类评分器（预算合规、精确匹配）负责给出稳定的下限，模型裁判负责评价"说得有没有道理"，两者搭配比只用其中一种更靠谱；rubric 写具体一点，裁判的方差会明显变小。
第 8 步：先跑一轮，观察实时过程
```bash
docker compose exec arena agentgarten trial run \
--task trials/budget-pick.yaml \
--agent price-hunter \
--watch
```
--watch 会在终端实时刷新每一轮的输入、智能体输出、各项得分和累计分。同时打开控制台页面，可以看到同样的过程：每一轮走完就立刻出分。如果终端里迟迟不出内容，先看 docker compose logs -f worker，大概率是队列或模型连接的问题。
这一轮跑完，记下总分和失分最多的评分项。这个基线很重要——进化有没有效果，全靠跟它比。
第 9 步：开启进化
在 evolution/ 下新建 evolution/default.yaml：
```yaml
population: 8
generations: 5
selection:
strategy: top_k
k: 3
mutation:
targets:
- prompt.system
- model.temperature
rate: 0.3
temperature_range: [0.2, 1.0]
early_stop:
metric: mean_score
patience: 2
```
启动：
```bash
docker compose exec arena agentgarten evolve start \
--task budget-pick \
--config evolution/default.yaml \
--watch
```
运行逻辑是这样的：先并行跑 8 个变体（population），每个变体在试炼任务上拿分；然后取分数最高的 3 个（top_k）作为父代，对它们的系统提示词和温度做变异，生成下一代；重复 5 代。early_stop 表示连续两代平均分没进步就提前收工，省 token。
监控页面上会看到一条分数曲线，横轴是代数，纵轴是平均分和最高分。这条曲线不涨是常态，别慌——先去看失分分布，往往是指令冲突或评分器太严。
第 10 步：看结果与最优个体
```bash
docker compose exec arena agentgarten result list --task budget-pick
docker compose exec arena agentgarten result show --run <run-id>
docker compose exec arena agentgarten agent export --id <最佳变体ID> -o best-agent.yaml
```
result show 会给出每一代的平均分、最高分，以及各个评分项的细分。把最优变体导出成 YAML，就能直接进生产或做下一轮人工打磨。
验证部署是否成功
按顺序做三个检查，全过就算部署完成：
```bash
1. 容器与服务健康
docker compose ps
期望：所有服务 running / healthy，没有反复重启
2. 试炼场接口可用
curl -s http://localhost:8080/healthz
期望：返回 {"status":"ok"} 一类 JSON
3. 模型与智能体可用
docker compose exec arena agentgarten provider test --name default
docker compose exec arena agentgarten agent list
期望：测试返回正常回复；列表中能看到已注册的智能体
```
最后再跑一遍第 8 步的单轮试炼，终端里能看到逐轮输出和最终总分，说明整条链路（智能体 → 模型 → 评分器 → 落库）都通了。
常见报错与解决
1. Error response from daemon: ports are not available: bind: address already in use
原因：ARENA_PORT 或数据库端口被其他进程占用。
解决：换端口后重启。
```bash
ss -lntp | grep 8080 # 看是谁占着
修改 .env 中的 ARENA_PORT 后
docker compose down && docker compose up -d
```
2. 容器启动几秒后退出，日志显示 connection refused 或 could not connect to server
原因：试炼场服务比数据库先起来，或者 DATABASE_URL 里的主机名、密码写错了。
解决：确认 compose 里数据库服务有健康检查、主服务有 depends_on: condition: service_healthy；再核对 .env 中的用户名密码。
```bash
docker compose logs db | tail -n 50
docker compose logs arena | tail -n 50
修正 .env 后
docker compose down && docker compose up -d
```
3. 模型调用报 401 Unauthorized 或 model not found
原因：API Key 失效、LLM_BASE_URL 缺路径后缀、模型名和接口实际提供的名字不一致。
解决：先在宿主机用 curl 直接打一次接口，把问题定位在密钥还是配置。
```bash
curl -s "$LLM_BASE_URL/chat/completions" \
-H "Authorization: Bearer $LLM_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"model\":\"$LLM_MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"hi\"}]}"
```
4. 试炼一直卡在 pending，控制台分数不动
原因：worker 没起来、队列连接失败，或单轮超时时间设得太短导致反复重试。
解决：先看 worker 日志，再确认 REDIS_URL 可达，最后把 timeout_seconds 调大。
```bash
docker compose ps worker
docker compose logs -f worker
必要时单独重启 worker
docker compose restart worker
```
5. 磁盘写满，服务开始报 No space left on device
原因：试炼记录和容器日志长期累积。
解决：清理旧运行记录，并给 Docker 配日志轮转。
```bash
df -h
docker system df
docker compose exec arena agentgarten result prune --older-than 30d
在 /etc/docker/daemon.json 配置 log-opts 的 max-size / max-file 后重启 Docker
```
后续维护
备份：三样东西要定期存——数据库（试炼记录、分数、进化谱系）、agents/ 与 trials/ 配置目录、导出的最优变体 YAML。
```bash
docker compose exec db pg_dump -U agentgarten agentgarten > backup-$(date +%F).sql
tar czf config-$(date +%F).tar.gz agents/ trials/ evolution/ .env
```
建议把这几条写进 crontab，每天跑一次，.env 记得单独加密存放。
升级：先看官方 CHANGELOG，确认配置字段有没有破坏性变更；再备份；然后在 docker-compose.yml 里把镜像 tag 固定成具体版本（别用 latest），执行 docker compose pull && docker compose up -d。升级后重跑一遍验证清单里的三个检查。
日志与监控：docker compose logs -f arena 和 worker 是最常用的两条。生产环境建议给 Docker 配置 max-size、max-file 做日志轮转，避免日志把盘吃满。关注这几个指标：每轮试炼的平均耗时、模型调用失败率、每代平均分的趋势、token 消耗。给 token 消耗设一个日预算告警，进化这类任务很容易在无人看管时把额度烧掉。
日常节奏建议：不要一上来就开大队列。先用 population: 4、generations: 3 小步试跑，确认评分器打分和人工判断方向一致，再放大规模。评分器不靠谱的时候，种群越大只是越快地把错误的答案放大而已。