model-compose：一个 YAML 文件搞定所有 AI 工作流

一个 YAML 文件。任意模型。任意协议。任意运行时。 无需一行 Python 代码，即可部署聊天 API、RAG 管道、自主智能体和 MCP 服务器——就像 docker-compose 那样简单。

---

痛点故事：为什么我们需要 model-compose？

凌晨两点，AI 工程师小李终于把公司的 RAG 问答系统跑通了。他兴奋地把 demo 分享给产品经理，对方在笔记本上折腾了半小时，最后卡在"Python 3.9 不兼容 pydantic 2.x"上。

这并不是个例。当前的 AI 应用开发面临三重困境：框架锁定（LangChain/Haydn 的抽象太重，改需求等于重写）、部署割裂（本地调通的 pipeline 到生产环境面目全非）、协议孤岛（OpenAI API、Anthropic、vLLM、MCP 各玩各的，无法互通）。

model-compose 正是为了解决这些问题而生——它不重复造轮子，而是让所有轮子用同一种语言说话。

---

项目背景：灵感来自 Docker-compose

model-compose 的核心灵感是 docker-compose：用一份声明式配置文件，描述多容器应用的拓扑关系，无需编写启动脚本就能在任何环境运行。

作者 Hanyeol Cho（韩国开发者）在 2024 年初开源了 model-compose，项目名称直指其核心理念——Compose Any AI, Deploy Anywhere。作者在 PyPI 上以 model-compose 发布，pip 单月下载量已达数万次。

该项目有 21 个 GitHub Topics 覆盖，从 llm-orchestration、mcp-server 到 rag、vector-database，定位非常清晰：AI 基础设施层。

---

核心功能：YAML 即一切

三大构建块

model-compose 用 YAML 描述 AI 系统的三个核心维度：

1. Component（组件）：模型、工作流、工具的原子单位

component:
  id: chatgpt
  type: http-client        # http-client | agent | rag | tool | ...
  base_url: https://api.openai.com/v1
  action:
    path: /chat/completions
    method: POST
    headers:
      Authorization: Bearer ${env....KEY}
    body:
      model: gpt-4o
      messages:
        - role: user
          content: ${input.prompt}

2. Workflow（工作流）：编排多个组件的执行顺序

workflow:
  job:
    component: chatgpt
    input:
      prompt: ${input.prompt}

3. Controller（控制器）：决定运行时行为（HTTP Server / MCP Server / Gradio UI）

开箱即用的组件生态

model-compose 并不重新发明 LLM SDK，而是通过适配器模式对接主流服务：

类型	支持列表
LLM Providers	OpenAI、Anthropic、Google (Gemini)、xAI (Grok)、vLLM（本地推理）
向量数据库	Chroma、Milvus、Qdrant、FAISS、Neo4j、ArangoDB、Redis
MCP Servers	内置 MCP 协议支持，可一键将工作流暴露为 MCP Server
音频/TTS	ElevenLabs 等
Agent 工具	Web Search、Page Fetch、代码执行等内置工具

独特的流式处理能力

model-compose 的 Stream-Native 原则在实现上非常优雅——令牌、音频块、视频帧均被建模为一等公民，支持端到端流式 pipeline 而无需等待上游全部完成：

workflow:
  job:
    component: chatgpt
    output: ${output as sse-text}

component:
  id: chatgpt
  type: http-client
  action:
    body: { stream: true }
    stream_format: json
    output: ${response[].choices[0].delta.content}

---

技术架构：分模块设计

从源码结构来看，src/mindor/core/ 下分为多个层次：

• component/：组件注册、运行时实例化、Action 解析。核心是 ComponentRegistry + ComponentResolver 模式。
• workflow/：工作流调度器，包含 WorkflowRunner（异步执行引擎）、WorkflowValidator（YAML schema 校验）、InterruptHandler（中断处理）和 Hook 系统。
• dsl/：YAML DSL 的解析层，使用 Pydantic 进行 schema 校验，正则解析 ${env...} 变量替换语法。
• foundation/：底层基础设施——异步服务、容器（containers/）、媒体处理（media/）、流式处理（streaming/）、变量系统（variable/）、提供商抽象（providers/）和速率限制（rate_limit.py）。
• cli/：基于 Click 实现的命令行工具，支持 up（启动）、down（停止）、logs（日志）等子命令。

框架依赖清晰：click（CLI）+ pydantic（配置校验）+ pyyaml（YAML 解析）+ fastapi（HTTP 服务）+ websockets（流式）+ mcp（MCP 协议）。无 LangChain 依赖是其轻量化的关键。

---

开发者体验：从 demo 到生产

本地开发（推荐起点）

pip install model-compose
export OPENAI_API_KEY=sk-...
model-compose up

自动在 http://localhost:8080 启动 API 服务，http://localhost:8081 启动 Gradio Web UI。

容器部署

controller:
  runtime:
    type: docker
    image: my-ai-service:latest
    ports: ["8080:8080"]

通过 YAML 声明运行时类型，无需额外 Dockerfile——runtime.type=docker 会在运行时自动构建。

水平扩展

通过内置队列（workflow.queue 配置），实现多消费者分发：

controller:
  adapter:
    type: dispatcher
  queue:
    type: redis

---

局限与争议

1. 深度定制受限：声明式 YAML 的代价是，当需求超出 DSL 表达能力时，用户只能退回到编写 Python 代码，此时 model-compose 的抽象反而成为负担。

2. 生态成熟度：相比 LangChain（2万+ stars）、AutoGen（3万+ stars），model-compose 的 76 stars 意味着社区贡献和插件生态都处于早期阶段，出了问题大概率需要自己看源码。

3. MCP 支持尚浅：MCP 协议本身在 2024 年才发布，model-compose 的 MCP Server 适配更多是尝鲜性质，生产级稳定性有待验证。

4. 安全风险：${env....KEY} 语法使用 re.VERBOSE 正则解析环境变量，若 YAML 配置文件被错误配置，可能存在变量注出的风险。

---

行业意义：声明式 AI 的探索者

model-compose 代表了一个正在兴起的设计哲学：AI 应用应该像基础设施一样声明式地管理。

类似 docker-compose 在容器编排领域的革命，model-compose 在 AI 编排领域的野心是——让业务开发者不需要成为 AI 工程师，也能组装出生产级的 AI 服务。当然，这条路能否走通，取决于社区的接受度和项目的持续投入。

适用人群：AI 产品经理、低代码 AI 平台开发者、需要快速搭建 AI demo 的研究人员。 不推荐：需要深度定制 LLM 行为、对延迟有极致要求的生产级应用。