Day 19 / 共 20 天 · 第 4 周 平台/异步/生态

部署与配置

SuperAGI 有多种部署形态（普通/GPU/本地 LLM）。今天详解 config.yaml 的关键配置，以及各种 docker 变体和生产考量。

📍 你在整门课的位置 · 第 4 周 平台/异步/生态
D16 API→ D17 Celery→ D18 GUI→ D19 部署与配置（跑到生产）→ D20 收官串讲
L01

config.yaml 全景

config_template.yaml（复制成 config.yaml）集中所有配置。分几大类：

类别关键项
LLMOPENAI_API_KEY / PALM / REPLICATE / MODEL_NAME / MAX_MODEL_TOKEN_LIMIT
数据库/队列DB_URL / REDIS_URL
存储STORAGE_TYPE (FILE/S3) / S3 配置
向量库PINECONE / RESOURCE_VECTOR_STORE 等
安全JWT_SECRET_KEY / 加密 key
工具凭据GOOGLE_API_KEY / 邮件 / GitHub / Jira / Slack …
💡 一句话本质 config.yaml = 整个平台的"总控制面板"。同一份代码，靠这一个文件切换：用哪家 LLM、文件存本地还是 S3、向量库用谁、接哪些工具。配置与代码分离——换环境只改配置，不动一行代码。
就像新房装修完的配电箱：房子结构（代码）不动，但每一路开关贴着标签——"照明"（LLM key）、"厨房"（存储）、"空调"（向量库）。想换供电方式不用砸墙重新布线，到配电箱拨一下开关就行。今天全程用"装修/水电"来理解部署配置。
⚠️ 小白常误以为：改完 config.yaml 保存就立即生效。其实：配置是容器启动时读进内存的——改完必须 docker compose restart，就像配电箱换了保险丝要重新合闸才通电。
"配置集中化"的好处 所有可调旋钮在一个文件——换模型改 MODEL_NAME、换存储改 STORAGE_TYPE、接工具填对应凭据。不用翻代码找配置、不用改多处。一份 config.yaml 决定整个平台的行为。这是 12-factor app 的"配置与代码分离"原则。
L02

LLM 配置

OPENAI_API_KEY: "sk-..."
MODEL_NAME: "gpt-4"              # 默认模型
MAX_MODEL_TOKEN_LIMIT: 8000     # 上下文上限
# 也可配 PALM/REPLICATE/HUGGING 的 key
读法：填哪家的 key + 设默认模型。Day 10 的 LLM 工厂根据 MODEL_NAME 查 DB 确定 provider、返回对应实现。MAX_MODEL_TOKEN_LIMIT 影响提示词的历史截断/压缩（Day 08）。"自带模型"——你填自己的 key，用自己的额度。
L03

存储配置

🤔 错误驱动：单机跑好好的，一上多容器/生产为什么文件就"丢"了？ 真实事故现场：智能体明明生成了报告，GUI 下载却 404。原因：backend 和 celery 是两个独立容器，各自有各自的本地磁盘。celery worker 把文件写到它自己容器的磁盘，backend 去它自己的磁盘找——当然找不到。这是新手部署最常踩的坑，解法就是下面这一行配置。
STORAGE_TYPE: "FILE"   # 或 "S3"
# S3 时：BUCKET_NAME / AWS key 等
FILE（多容器时出错） celery 容器写→本地磁盘A backend 容器读→本地磁盘B ✗ 两块磁盘互不相通，读不到 S3（共享存储 ✓） celery 容器 backend 容器 S3 共享桶 写 读
同一份代码，STORAGE_TYPE 从 FILE 改成 S3——就把"各写各的磁盘"变成"共用一个桶"，多容器才能互通。
📝 就改一行，行为全变 单机开发：STORAGE_TYPE: "FILE"——够用、零依赖。
上生产/多 worker：改成 STORAGE_TYPE: "S3" + 填 BUCKET/AWS key，重启容器——celery 写的文件 backend 立刻能读到。业务代码一行没动（这就是 Day 14 可插拔存储的价值）。
FILE vs S3 怎么选（Day 14 复习） FILE（本地）：单机开发够用。S3（云）：生产/多实例必须——因为 backend 和 celery 是不同容器，本地磁盘各容器不通，只有 S3 这种共享存储才能让"celery 写的文件、backend 能读到"。单机用 FILE，多容器/生产用 S3——改一行配置切换（Day 14 的可插拔存储）。
用装修类比：FILE 是"各房间自己的抽屉"——一个人住随手放没问题；S3 是"楼下的公共快递柜"——多个住户（容器）要传东西，必须放进大家都有钥匙的柜子里。
L04

向量库配置

配置向量库类型（Day 13）：可选 Pinecone/Weaviate/Qdrant/Redis。默认 Redis（super__redis 用的 redis-stack-server 自带向量能力，Day 04）。资源文件 RAG 用 RESOURCE_VECTOR_STORE（默认 Redis）。

👶🏫 对话：Redis 不是消息队列吗，怎么又当向量库？ 👶 小白：Day 17 说 Redis 是 Celery 的小票夹，怎么这里又拿它存向量？
👨‍🏫 老师：SuperAGI 用的是 redis-stack-server——带"扩展包"的 Redis，自带向量检索模块。一个组件干两份活。
👶 小白：那为什么不直接上更专业的 Pinecone？
👨‍🏫 老师：Pinecone 要注册账号、填 key、多一个外部依赖——新手起步的门槛就高了。装修时优先用房子里已有的线路，不够用再单独拉专线。默认 Redis 就是"先用已有的"，量大了再换。
为什么默认 Redis？ 因为平台本来就有 Redis（Celery broker），用 redis-stack-server 顺便当向量库——少一个外部依赖（不用额外部署 Pinecone）。要更强的向量检索能力（大规模、高级过滤）再换 Pinecone/Qdrant。默认用已有组件、可选升级——降低起步门槛。
L05

docker 变体

仓库有多个 docker-compose 变体：

  • docker-compose.yaml：标准（Day 04）。
  • docker-compose-dev.yaml：开发（热重载等）。
  • docker-compose-gpu.yml：GPU 支持（跑本地大模型）。
  • docker-compose.image.example.yaml：用预构建镜像（不本地 build，更快）。
为什么这么多变体？ 不同场景需求不同：开发要热重载（改代码即生效）；跑本地大模型要 GPU；快速部署用预构建镜像（不用本地编译）。提供多个 compose 文件，用户按场景挑一个 docker compose -f xxx.yaml up。还有 local-llm/local-llm-gpu 目录、tgwui（text-generation-webui）支持——为"接本地开源模型"准备。
L06

本地开源模型

SuperAGI 支持接本地开源模型（不用 OpenAI）——通过 Local LLM provider（Day 10 工厂的一个分支）、local-llm/tgwui 目录、GPU compose。

为什么要支持本地模型？ ① 隐私：数据不出本地（敏感场景不能发给 OpenAI）；② 成本:自己的 GPU 跑，不按 token 付费；③ 可控:不依赖外部 API 的可用性/限流。代价:要有 GPU、本地模型能力可能不如 GPT-4。SuperAGI 的 LLM 抽象（Day 10）让"换成本地模型"只是注入一个 LocalLLM 实现——业务代码不变。这就是抽象层的价值：接本地模型和接 OpenAI 对上层一样。
L07

生产考量

  • 存储用 S3：多容器共享（L03）。
  • Celery worker 多开：扛并发智能体（Day 17 的水平扩展）。
  • 密钥安全：config.yaml 里的 key 要保护好（别提交进 git）；工具凭据加密存 DB（Day 12）。
  • 数据库：生产用托管 Postgres（而非容器内的），有备份。
  • 成本控制：MAX_ITERATIONS（Day 02 熔断）+ 监控 token 用量（Execution.num_of_tokens）。
从"跑起来"到"生产可用"：docker compose 一键起是为了体验/开发。生产要考虑存储共享、worker 扩展、密钥安全、数据库可靠、成本控制。这些是把任何"能跑的 demo"变成"可靠服务"的通用考量——不只 SuperAGI。
L08

今日小结 + 动手

🧠 今天你应该能回答

  • config.yaml 有哪几大类配置？
  • 存储 FILE vs S3 怎么选？为什么多容器必须 S3？
  • 为什么默认向量库用 Redis？
  • 为什么有多个 docker 变体？
  • 为什么支持本地模型？抽象层在这的价值？生产考量有哪些？

✋ 动手

grep -nE 'API_KEY|MODEL_NAME|STORAGE_TYPE|REDIS_URL|VECTOR_STORE|JWT' config_template.yaml | head
ls docker-compose*.yaml local-llm* tgwui 2>/dev/null
grep -n 'Local LLM' superagi/llms/llm_model_factory.py
明天预告 · Day 20（结业）：构建测试与收官串讲——从零搭智能体的清单、常见坑、20 天知识地图、SuperAGI 设计哲学、五框架终极横向对比。
← Day 18 GUI Day 20 · 收官 →