Agents-A1 在开发环境中快速启动的配置清单

Agents-A1 在开发环境里跑起来，不需要把全部组件都装上。关键路径是先确认本机 Python 环境能加载推理框架，再准备好模型权重，然后用最小配置启动服务。这样做的目标是让服务先能接收请求并返回结果，后续再逐步加参数。

适用场景：本地开发机或内网测试环境，需要快速拉起 Agents-A1 做接口联调。操作动作：安装基础 Python 包、下载模型权重到约定目录、编写最小 YAML 配置、启动服务并 curl 健康接口。验证方式：健康接口返回正常且日志无异常。风险边界：该配置不面向高并发和生产部署，模型路径和设备参数需要结合具体安装环境确认，首次加载会因模型大小和硬件性能有等待时间。

确认环境依赖与Python包

开始前先确认 Python 环境可用，建议使用独立虚拟环境，避免把开发机的基础环境弄乱。Agents-A1 启动时需要四类包：深度学习框架（用于加载模型）、模型加载库（用于读取权重）、Web 服务和 ASGI 服务器（用于提供 HTTP 接口）、配置文件解析库。可以用下面命令一次性安装：

pip install torch transformers fastapi uvicorn pyyaml

这里没有写版本号，因为不同硬件和 Python 版本对框架版本有要求。建议先装好 torch，再装其他包；如果用的是 GPU 环境，torch 的安装命令要与你本机的 CUDA 版本匹配，这一点需要结合环境确认。

安装完成后，用 python -c 'import torch, transformers, fastapi, yaml; print("ok")' 验证包是否能被正常导入。如果导入失败，优先排查是否装到了当前激活的虚拟环境里。

下载模型权重并放在指定目录

Agents-A1 需要加载模型权重文件，光有代码没有权重是启动不了的。建议把权重放在项目内固定的 models/Agents-A1 目录下，这样配置和启动脚本都比较短。目录结构通常为：

models/Agents-A1/
├── config.json
├── tokenizer.json
└── model.safetensors

权重文件较大，下载后需要检查是否完整。进入目录后执行 ls -l 确认文件非空，再用 du -sh models/Agents-A1 查看整体大小。如果目录里没有 config.json，说明权重不完整，启动时会报缺文件错误。

编写最小启动配置

最小启动配置只需要包含端口、模型路径和设备选择三个部分。把下面内容保存为 config/agents_a1.yaml：

server:
  host: "127.0.0.1"
  port: 8000

model:
  path: "./models/Agents-A1"
  device: "auto"

log:
  level: "INFO"

其中 device 可以写成 auto，让框架自己判断可用设备。如果开发机没有 GPU，auto 会退回 CPU，但启动时间会变长。建议第一次启动时保持 127.0.0.1，不要直接绑定 0.0.0.0，避免暴露到局域网。

启动服务并检查健康接口

启动命令根据入口脚本不同会有差别。如果项目自带了启动脚本，可以直接执行：

python start.py `--config` config/agents_a1.yaml

看到日志出现类似 Uvicorn running on http://127.0.0.1:8000 的信息后，另开一个终端检查健康接口：

curl http://127.0.0.1:8000/health

正常情况下会返回一个 JSON 字符串，比如 {"status":"ok"}。如果连接被拒绝，先确认启动日志里有没有报错；如果健康接口一直无响应，查看进程是否还活着，以及端口是否被其他程序占用。开发环境中常见的问题是端口冲突，修改 YAML 里的 port 再重启即可。

设置环境变量以调整运行模式

Agents-A1 支持通过环境变量覆盖配置文件里的部分内容，方便在不同机器上切换调试和部署模式。常用变量包括：

LOG_LEVEL：日志级别，调试时设为 DEBUG，正常运行时保持 INFO。
CACHE_DIR：模型缓存路径，避免每次启动都重新加载临时数据。
USE_GPU：是否强制使用 GPU，取 0 或 1。
MAX_INPUT_LENGTH：输入长度上限，用于控制请求体大小。

设置示例（Linux 或 macOS 下）：

export LOG_LEVEL=DEBUG
export CACHE_DIR="./cache"
export USE_GPU=1
python start.py `--config` config/agents_a1.yaml

设置环境变量时要注意，USE_GPU=1 只表示强制使用 GPU，如果机器没有可用 GPU，启动会直接报错，因此建议先以 auto 模式启动一次，确认设备识别正确后再改环境变量。缓存目录需要提前创建，否则程序可能因为找不到目录而退出。