0%

背景

最近,关于 AI Agent 如何与外部系统交互的讨论非常热烈,尤其是围绕 MCP 和 CLI 的争论。很多人认为 MCP 因为成本高、效率低而即将被淘汰。但就在四月二十二日,MCP 的”亲爹”Anthropic 发布了一篇重磅博客,为我们揭示了一个全新的视角。本文将深入解读这篇文章,探讨 MCP 的现状挑战以及它真正的未来。


一、社区对 MCP 的三大”罪状”

1.1 成本太高

根据 ScaleKit 的严格测试,在相同操作下:

方案 成本对比
CLI 基准成本
MCP 17倍于 CLI

这意味着使用 MCP 的成本是 CLI 的 17 倍,这是一个巨大的差距。

1.2 上下文占用严重

Perplexity 的 CTO 直言他们内部正在远离 MCP,原因惊人:

1
MCP 占用了高达 72% 的宝贵上下文窗口

对于需要长上下文的复杂任务,这几乎是不可接受的。

1.3 Schema 过于臃肿

以 GitHub 的 MCP 为例:

数据项 数值
工具数量 43 个
单工具描述 Token 4026 Token
每次交互 全部 43 个工具定义都要发给模型

每次交互都要把 43 个工具的”说明书”全部发给模型,光工具定义就占用了大量 Token,这无疑是巨大的浪费。


二、官方回应:三种连接方式,各有其场

面对这些批评,Anthropic 并没有直接反驳,而是给出了一个更宏观的框架。

2.1 Agent 连接外部系统的三种方式

方式 适用场景 优势 劣势
直连 API 简单场景 直接、快速 扩展性差,陷入 M×N 集成噩梦
CLI 本地环境 高效、灵活 无法在云端运行
MCP 云端环境 标准化、跨平台 成本较高

2.2 Anthropic 承认 CLI 的优势

Anthropic 大方承认:CLI 在本地环境确实高效。但他们强调了一个关键趋势:

1
越来越多的生产级 Agent 正在云上运行

在云端环境中:

  • 没有本地文件系统
  • 无法执行 CLI 命令
  • 如 Claude 网页版、移动端 App

MCP 的价值就体现出来了:它提供了一个标准化的远程连接层,能统一服务于各种客户端。

2.3 MCP 的全新定位

Anthropic 为 MCP 找到了一个全新的、也是它最该待的地方:

1
云端 Agent 的标准化接入层

无论是网页版的 Claude,还是集成在 VS Code 里的 Cursor,都可以通过一个统一的 MCP 服务器来访问后端服务。这个定位非常清晰。

2.4 市场数据印证

时间节点 MCP SDK 月下载量
早期 1 亿
当前 3 亿

短短几个月内下载量翻了 3 倍,这说明开发者们正在积极拥抱这个标准。


三、核心解法一:Tool Search(工具搜索)

Anthropic 提出了两个核心技术解法来解决 Token 消耗问题。

3.1 传统方式的痛点

1
2
3
传统方式:
每次交互 → 把一整本厚厚的说明书(全部工具定义)塞给模型
→ 巨大的 Token 消耗

3.2 Tool Search 的思路

1
2
3
Tool Search 方式:
模型先告诉系统它想做什么 → 系统去"书架"上找到对应的那几页说明书
→ 只把相关工具定义发给模型

核心理念:工具应该围绕用户意图来组织,而不是简单地按 API 来划分。

3.3 效果数据

指标 效果
工具定义 Token 减少 超过 85%
工具选择准确率 保持不变

这种”按需加载”的方式能直接砍掉超过 85% 的工具定义 Token,而且工具选择的准确率并没有降低。


四、核心解法二:程序化工具调用

第二个解法思路非常巧妙,它改变了工具返回结果的处理方式。

4.1 传统方式的问题

1
2
传统方式:
工具返回大量原始数据 → 直接涌入模型的上下文 → 上下文爆炸

4.2 程化调用的思路

1
2
3
程序化调用方式:
模型在安全的代码沙箱里写一小段代码 → 处理数据(过滤、计算、整合)
→ 只把精炼后的结果返回给模型

核心理念:别让模型当搬运工,让它写代码。

4.3 效果数据

任务类型 Token 减少幅度
复杂任务 约 37%

根据官方数据,这个方法在处理复杂任务时能额外减少约 37% 的 Token 消耗。


五、两个解法的综合效果

拿之前 ScaleKit 的测试数据来算一笔账:

5.1 原始差距

1
2
原始情况下:
MCP Token 消耗 = CLI 的 32 倍

这是一个巨大的鸿沟。

5.2 应用解法后

方案 Token 消耗估算
原始 MCP 约 32000 Token
Tool Search 后 约 10000 Token
CLI 约 1000 Token

差距从 32 倍缩小到约 7 倍。

5.3 成本合理性分析

虽然 MCP 还是比较 CLI 更贵,但这个差距已经不再是不可逾越的了。在云端环境下,MCP 带来的:

  • 标准化
  • 安全性
  • 跨平台能力

其价值完全可以覆盖这部分成本差异。


六、实战案例:Cloudflare 的聪明做法

理论说再多不如看一个实际案例。Cloudflare 是 MCP 的深度用户。

6.1 他们面临的挑战

1
需要通过 MCP 开放约 2500 个 API 端点

如果按传统方式,这简直是一场灾难。

6.2 聪明的解决方案

Cloudflare 的做法非常聪明:

设计 说明
对外暴露工具数 只有 2 个
工具名称 search + execute

6.3 工作流程

1
2
3
Agent 工作流程:
1. 用 search 找到需要的 API
2. 通过 execute 在服务端执行操作(像写脚本一样)

6.4 效果

指标 数值
工具定义 Token 约 1000 Token

这个案例完美诠释了 Anthropic 的理念:MCP 服务器应该像 CLI 一样设计,让 Agent 通过代码来编排和控制


七、MCP 与 Skills 的生态融合

除了解决技术问题,Anthropic 还在推动生态的融合。

7.1 MCP 与 Skills 的关系

角色 职责 类比
MCP 连接各种服务,提供”能力” 工具箱
Skills 告诉 Agent 如何使用能力完成任务 操作手册

7.2 Claude 数据插件案例

Claude 的数据插件是一个典型例子:

组成 数量
Skills 10 个
MCP 服务器 8 个

用户可以轻松地分析来自不同数据库的数据。

7.3 第三方服务商跟进

像 Canva、Notion 这些第三方服务商也开始效仿:

1
发布 MCP 服务器 + 配套 Skills

这标志着一个更加成熟和协同的 Agent 生态正在形成。


八、总结:未来的分工格局

Anthropic 的这篇博客,并非对社区批评的简单反驳,而是一次深刻的自我进化和战略澄清。

8.1 针对三大痛点的解决方案

痛点 解决方案
成本太高 Tool Search(减少 85% 工具定义 Token)
上下文占用 程序化调用(减少 37% 结果 Token)
Schema 臃肿 代码编排模式(Cloudflare 案例)

同时,Anthropic 也大方承认了 CLI + Skills 模式的价值,并将 Skills 正式纳入了官方最佳实践。

8.2 MCP 的主战场

1
云端和跨平台环境 → MCP 是目前唯一合理的标准化解决方案

8.3 未来的分工格局

环境 最佳实践
云端生产环境(面向用户的 SaaS) MCP + Skills
开发者本地环境 CLI + Skills
简单任务 直连 API

不存在一个万能的解决方案,Agent 时代的连接层正在走向多元化和专业化。


附录:关键数据汇总

数据项 来源 数值
MCP vs CLI 成本差距 ScaleKit 测试 17 倍
MCP 上下文占用 Perplexity CTO 72%
GitHub MCP 工具数 官方 Schema 43 个
Tool Search Token 减少 Anthropic 85%+
程序化调用 Token 减少 Anthropic 37%
MCP SDK 月下载量 npm 数据 3 亿
Cloudflare 工具定义 Token 实战案例 1000

结论

MCP 并没有死,它只是找到了属于自己的战场。Agent 时代的连接层正在走向多元化和专业化。作为技术从业者,我们需要理解不同工具的适用场景,并根据自己的业务需求做出最合适的技术选型。


参考资源

写在前面

2026 年 4 月,中国。

你想订阅一个 Coding Plan?那得费老鼻子劲了。

这不是个例。2026 年,中国的 AI 算力供应紧张到了”抢号”的地步。

背后的原因很简单:高端 GPU 被禁售,国产替代跟不上。

这篇文章,聊聊中国显卡自研的进度、挑战,以及算力危机暴露出的深层问题。


一、现状:2026 年的国产 GPU

1.1 华为昇腾:国产 AI 算力的主力

华为昇腾是目前国产 AI 算力最有希望的产品线:

产品 制程 状态 性能对标
昇腾 910B 7nm (中芯N+2) 已量产 约 A100 水平(2020年)
昇腾 910C 7nm 小规模量产 约 A100/A800 水平
昇腾 910D 7nm+ 2025H2量产,2026部署 目标对标 H100

时间差距评估:

如果昇腾 910D 成功对标 H100(2022 年产品),那么:

1
2
3
4
5
6
7
8
性能对标:    昇腾 910D ≈ H100 (2022)
↙ ↘
时间差距: 2026年达到 → 2022年水平 = 落后 4 年

但同时 NVIDIA 已演进到:
B200/B300 (2024-2025) + Rubin (2026)

仍领先 2-3 代

1.2 其他国产 GPU 厂商

厂商 产品 制程 状态 定位
海光 DCU 系列 7nm 已量产 CUDA 兼容,持续迭代
壁仞科技 BR100 改版 7nm 小规模 转型推理、边缘计算
摩尔线程 MTT S80/S4000 7nm 已量产 全功能 GPU,消费级+专业级
天数智芯 天垓 100 7nm 已量产 AI 推理

共同特点: 全部停留在 7nm 制程


二、硬件瓶颈:制程封锁是核心困境

2.1 光刻机:无法获得的”关键设备”

高端 GPU 需要先进制程。而先进制程依赖光刻机

制程 生产方 中国可获得性
3nm TSMC、三星 ❌ 完全封锁
4nm/4NP TSMC ❌ 禁止出口中国
5nm TSMC、三星 ❌ 禁止出口中国
7nm TSMC、三星、中芯 ⚠️ 中芯可做,但产能有限
14nm+ 中芯、华虹等 ✅ 成熟量产

2026 年实际差距:

1
2
3
4
5
6
7
8
9
NVIDIA 制程演进:
2022: H100 @ 4nm
2024: B200 @ 4NP (改进4nm)
2026: Rubin @ 3nm

中国可获得的最佳制程:
2026: 7nm (中芯 N+2,DUV 多重曝光)

制程差距: 3nm vs 7nm = 2-3 代差距

2.2 EUV vs DUV:光刻机的代际差距

EUV(极紫外光刻机) 是制造 7nm 以下芯片的关键设备,由荷兰 ASML 生产,被美国禁止出口中国。

中芯国际只能用 DUV(深紫外光刻机) 做 7nm,需要”多重曝光”:

指标 EUV 单次曝光 DUV 多重曝光
步骤数 1次曝光 3-4次曝光
良率 80-90% 30-50%
成本 基准 2-3 倍
产能 基准 限制较大

这意味着:

  • 同样生产一块 7nm GPU,中国成本更高、良率更低
  • 实际可用芯片数量有限,无法大规模量产
  • 7nm 是天花板,无法突破到 5nm/3nm

2.3 HBM 内存:另一个短板

高端 AI 训练需要 HBM(高带宽内存)

GPU 内存规格 带宽
H100 80GB HBM3 3.35 TB/s
B200 192GB HBM3e 8 TB/s
昇腾 910D 估计 HBM2e 估计 1-2 TB/s

HBM 由韩国 SK 海力士、三星主导,技术门槛极高。国产 HBM 还在研发阶段,差距明显。


三、软件瓶颈:CUDA 的二十年差距

3.1 CANN vs CUDA:软件栈差距

华为昇腾使用 CANN(Compute Architecture for Neural Networks)作为软件栈:

1
2
3
4
5
6
7
8
9
10
CUDA 生态层级              CANN 生态层级
┌─────────────────┐ ┌─────────────────┐
│ PyTorch/TF │ │ MindSpore │ ← 华自研框架
├─────────────────┤ ├─────────────────┤
│ cuDNN/cuBLAS │ │ ACL/OP API │ ← 适配层
├─────────────────┤ ├─────────────────┤
│ CUDA Runtime │ │ CANN Runtime │
├─────────────────┤ ├─────────────────┤
│ NVIDIA GPU │ │ 昇腾 NPU │
└─────────────────┘ └─────────────────┘

差距对比:

维度 CUDA (2026) CANN (2026)
开发周期 20 年 约 6-7 年
开发者数量 500 万+ 估计 15-20 万
算子库数量 3000+ 估计 500-600 个
文档完善度 极其详尽 相对不足
bug 修复速度 全球团队支持 依赖华为内部团队

3.2 深度学习框架的适配困境

主流框架对 CUDA 是”原生级”支持,对昇腾是”适配级”:

1
2
3
4
PyTorch 官方支持优先级:
├── CUDA: 原生支持,性能最优,bug 优先修复
├── ROCm (AMD): 次级支持,问题较多
└── CANN (昇腾): 通过 torch_npu 扩展适配,非官方原生

这意味着:

  • PyTorch 新特性永远先在 CUDA 上实现
  • 昇腾适配永远慢一步
  • 很多算子没有优化实现
  • 开源社区贡献几乎为零

3.3 算子移植的巨大工作量

一个深度学习模型可能有 数百个算子

对比 数量
PyTorch CUDA 算子 超过 2000 个
昇腾已适配算子 估计 500-800 个
差距 超过 1200 个算子需要移植

每个算子都需要:

  • 针对昇腾架构重新实现
  • 性能优化调优
  • bug 测试修复

这是一项巨大且持续的工作


四、人才瓶颈:GPU 专家在哪里?

4.1 GPU 架构设计人才稀缺

需要的人才类型 全球分布
GPU 微架构设计 主要在 NVIDIA、AMD,中国极少
并行计算编译器 CUDA 团队深耕 20 年,中国刚起步
高性能算子优化 需要硬件+算法双重知识,人才稀缺

现实: 全球 GPU 核心人才集中在 NVIDIA 和 AMD。中国需要”从零培养”或”海外引进”,但顶尖人才很难回国。

4.2 开发者转向成本

即使硬件做出来了,谁来用?

  • 中国 AI 开发者 90%+ 使用 CUDA
  • 学习 CANN 需要重新理解:编程模型、内存管理、性能优化策略
  • 企业没有动力让员工学习新平台(除非强制)

五、追赶悖论:永远差几步

5.1 时间差距的变化

1
2
3
4
5
6
7
8
9
10
11
12
时间差距变化:
2024: 昇腾 910B vs H100 = 落后约 6-8 年
2026: 昇腾 910D vs B300 = 落后约 3-4 年

如果保持追赶速度:
2028: 可能落后 2-3 年
2030: 可能落后 1-2 年

但前提是:
├── 制程不被进一步封锁
├── 软件生态持续投入
└── NVIDIA 不加速迭代

5.2 NVIDIA 也在前进

更残酷的是:你追上今天的 NVIDIA,但 NVIDIA 又进化了。

1
2
3
4
5
6
7
8
9
10
11
12
13
2026 年时间线:

NVIDIA:
├── H100 (2022) ─────→ 成熟稳定,大规模部署
├── B200/B300 (2024-2025) ─→ 大规模出货
└── Rubin R100 (2026H2) ─→ 下一代发布

华为昇腾:
├── 910B (已量产) ─────→ 对标 A100 (2020)
├── 910C (小规模) ─────→ 对标 A100/A800
└── 910D (2026部署) ───→ 目标对标 H100 (2022)

差距:4 年(但 NVIDIA 还有 B300、Rubin)

六、挑战排序:从难到易

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
                    ┌─────────────────────────────────┐
│ 中国 GPU 自研挑战金字塔 │
└─────────────────────────────────┘

Level 5: 生态网络效应(差距扩大)
├── CUDA 20 年,开发者 500 万+
├── 学术界默认 CUDA,论文难复现
└── 全球开源社区全部绑定 CUDA

Level 4: 软件栈深度(差距缩小但仍明显)
├── 算子库 3000+ vs 600
├── PyTorch 适配约 70% 主流算子
└── 调试工具、profiler 差距大

Level 3: 人才知识积累(持续投入)
├── 20 年培养的 GPU 专家
├── 编译器团队规模差距
└── 性能优化经验积累

Level 2: 制造工艺差距(核心瓶颈)
├── 3nm vs 7nm,差 2-3 代
├── EUV 光刻机完全封锁
└── HBM 内存技术落后

Level 1: 硬件架构设计(已有突破)
├── 昇腾 910D 架构设计成熟
├── 部分指标接近 H100
└── 资金投入可解决

排序结论:

  • 硬件设计(Level 1):已有突破,可追赶
  • 制造工艺(Level 2):核心瓶颈,短期难以突破
  • 人才积累(Level 3):需要持续投入 5-10 年
  • 软件栈(Level 4):差距明显,但正在缩小
  • 生态效应(Level 5):差距扩大,最难跨越

七、算力危机:暴露了哪些问题?

7.1 表层问题:供应不足

2026 年,Coding Plan 抢不到,直接原因是:

问题 说明
NVIDIA GPU 禁售 H100、B200 等高端产品无法进口
国产 GPU 产能不足 7nm 良率低,产能有限
需求爆发式增长 大模型训练需求远超供给

7.2 深层问题:技术依赖

更深层的问题是技术依赖

依赖类型 说明
硬件依赖 高端 GPU、光刻机、HBM 都依赖进口
软件依赖 CUDA 生态绑定,开发者只会 CUDA
人才依赖 GPU 核心人才在海外
生态依赖 学术论文、开源项目全部绑定 CUDA

一句话:AI 技术栈的每一层,都依赖海外技术。

7.3 更深层问题:战略误判

回顾过去十年,有哪些战略误判?

误判 后果
低估 AI 算力重要性 2022 年大模型爆发时,措手不及
低估制裁风险 没有”囤货”预案,禁售后严重短缺
高估国产替代速度 认为几年就能追上,实际差距仍大
忽视软件生态 只关注硬件,软件生态投入不足

八、未来展望:什么时候可以缓解?

8.1 短期(2026-2027)

方面 预期
昇腾 910D 部署 2026 年大规模部署,缓解部分需求
国家强制替代 政企、国企强制使用国产算力
算力共享平台 建立公共算力平台,提高利用率

缓解程度: 部分缓解,但高端需求仍紧张。

8.2 中期(2028-2030)

方面 预期
昇腾下一代 目标对标 B300,差距缩小到 2-3 年
软件生态成熟 CANN 算子适配 90%+,MindSpore 完善
7nm 产能提升 中芯产能提升,良率改善

缓解程度: 基本需求可满足,高端训练仍有限制。

8.3 长期(2030+)

方面 预期
制程突破? 取决于光刻机技术突破,不确定性高
生态建立 国内开发者形成规模,可能突破 50 万
差异化路线 不追求通用 GPU,聚焦特定领域优化

缓解程度: 取决于技术突破和持续投入。

8.4 关键变量

什么时候可以缓解,取决于三个变量:

变量 影响
美国制裁力度 制程封锁是否会进一步加强
软件生态投入 CANN、MindSpore 能否持续迭代
国内需求增速 大模型需求是否会放缓

九、可能的破局路径

9.1 短期:强制替代

1
2
3
4
5
国家强制推动:
├── 政务系统 → 强制使用国产算力
├── 国企央企 → 强制使用国产算力
├── 高校科研 → 优先使用国产算力
└── 互联网公司 → 部分强制替代

优点: 快速提升国产 GPU 需求,加速迭代
缺点: 效率损失,短期内性能不如 CUDA

9.2 中期:场景突破

不追求”通用 GPU”,聚焦特定场景:

场景 策略
推理场景 不需要顶级算力,国产 GPU 可胜任
边缘计算 功耗要求高,国产 GPU 有优势
特定行业 政务、金融、医疗,可以定制优化

9.3 长期:生态建设

1
2
3
4
5
开源社区建设:
├── 投资开源项目 → 让开发者愿意贡献
├── 建立开发者社区 → 提供培训、文档、支持
├── 学术合作 → 让高校用国产 GPU 做研究
└── 企业扶持 → 帮助企业迁移到国产平台

这是最难但最根本的路径。


十、总结:路还要走多久?

回到开头的问题:Coding Plan 抢不到,什么时候可以缓解?

答案取决于视角:

视角 时间估计
基本需求缓解 2026-2027(昇腾 910D 部署)
高端需求缓解 2028-2030(取决于技术突破)
追上 NVIDIA 可能需要 10-15 年
建立完整生态 可能需要 20 年

更关键的问题:

算力危机暴露的不仅是”供应不足”,而是整个 AI 技术栈的依赖

  • 硬件依赖:光刻机、GPU、HBM
  • 软件依赖:CUDA 生态
  • 人才依赖:GPU 专家稀缺
  • 生态依赖:学术界、开源社区

这不是”买买买”就能解决的问题,而是需要 10-20 年持续投入的系统性工程。


写在最后

中国显卡自研之路,注定是一条艰难的路。

硬件层面:制程封锁是核心瓶颈,短期难以突破。

软件层面:CUDA 的二十年差距,需要持续追赶。

生态层面:开发者、学术界、开源社区的绑定,是最难跨越的障碍。

但好消息是:

  • 昇腾 910D 如果成功量产,将大幅缩短差距
  • CANN/MindSpore 正在快速迭代
  • 国产替代需求 正在加速推动技术进步

中国 GPU 自研,不是”能不能”的问题,而是”要多久”的问题。

短期(2-3 年):基本需求缓解。
中期(5-8 年):高端需求部分满足。
长期(10-15 年):可能追上 NVIDIA。

但前提是:制裁不加剧、投入不中断、生态持续建设。


参考资料

一、前言:为什么需要这个工具?

你有没有遇到过这样的场景:

  • 想让 AI 帮你调试网页,但它只能”纸上谈兵”,给建议却不能动手
  • 需要自动化测试网页功能,写脚本太麻烦
  • 想分析网页性能瓶颈,但看不懂 DevTools 里的各种指标
  • 希望让 AI 帮你截取网页截图、提取页面内容

Chrome DevTools MCP 就是解决这些问题的神器。它让 AI 助手(如 Claude Code、Cursor、Copilot)能够直接操控浏览器,像一个真正的开发者一样干活。


二、核心概念:MCP 是什么?

2.1 MCP 协议简介

MCP(Model Context Protocol) 是 Anthropic 在 2024 年底提出的一个开放协议。简单理解,它是 AI 助手与外部工具之间的”通用插座”。

打个比方:

  • 没有 MCP 时,AI 像是”被困在盒子里的聪明人”——只能聊天,不能动手
    -有了 MCP,AI 像是”长了手脚的助手”——能连接数据库、操控浏览器、读写文件

2.2 MCP 的架构

1
2
3
4
5
6
7
8
9
10
┌─────────────┐     MCP 协议     ┌─────────────────┐
│ AI 助手 │◄──────────────►│ MCP Server │
│ (Claude等) │ │ (工具提供者) │
└─────────────┘ └─────────────────┘


┌─────────────────┐
│ 外部资源 │
│ (浏览器/数据库等)│
└─────────────────┘

MCP Server 是关键组件,它:

  1. 暴露工具(Tools)给 AI 调用
  2. 提供资源(Resources)供 AI 读取
  3. 发送提示(Prompts)引导 AI 使用

2.3 Chrome DevTools MCP 的定位

chrome-devtools-mcp 是官方提供的 MCP 服务器,它把 Chrome 浏览器的 DevTools 能力 暴露给 AI 助手。

这意味着 AI 可以:

  • 打开网页、点击按钮、填写表单
  • 查看控制台日志、网络请求
  • 截图、分析性能
  • 提取 DOM 元素、调试 JavaScript

三、核心功能一览

3.1 主要能力分类

类别 功能 典型用途
浏览器控制 打开页面、导航、刷新、关闭 自动化浏览
页面交互 点击、输入文本、滚动、等待 自动化测试
调试分析 控制台日志、网络请求、错误追踪 问题排查
性能分析 录制性能追踪、分析加载时间 性能优化
视觉捕获 截图、获取元素坐标 文档记录
DOM 操作 获取元素、查询选择器 内容提取

3.2 Slim 模式 vs 完整模式

Chrome DevTools MCP 提供两种运行模式:

模式 工具数量 适用场景 启动参数
Slim 模式 约 10 个 基础浏览任务 --slim --headless
完整模式 约 30+ 个 调试、性能分析 默认

新手建议先用完整模式,熟悉后再根据需求切换。


四、安装配置:Claude Code 实战

4.1 环境要求

在开始之前,请确保你有:

要求 版本 检查方法
Node.js v20.19+ node -v
npm 最新版 npm -v
Chrome 最新稳定版 浏览器设置查看
Claude Code 最新版 claude --version

4.2 方法一:CLI 快速安装(推荐)

打开终端,执行一行命令:

1
claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest

这会自动添加到你的用户级配置中。

4.3 方法二:手动配置

如果你想手动配置,找到 Claude Code 的配置文件:

Windows:

1
C:\Users\<你的用户名>\.claude\settings.json

Mac/Linux:

1
~/.claude/settings.json

mcpServers 部分添加:

1
2
3
4
5
6
7
8
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": ["-y", "chrome-devtools-mcp@latest"]
}
}
}

4.4 配置参数详解

你可以通过参数定制行为:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": [
"-y",
"chrome-devtools-mcp@latest",
"--headless", // 无头模式(不显示浏览器窗口)
"--slim", // 精简模式(减少工具数量)
"--no-performance-crux" // 禁用 CrUX 数据收集
]
}
}
}

常用参数说明:

参数 作用 建议场景
--headless 无界面运行 CI/CD、自动化脚本
--slim 只加载基础工具 简单浏览任务
--no-usage-statistics 禁用使用统计 隐私敏感场景
--browser-url=... 连接已有浏览器 调试特定实例

4.5 验证安装

重启 Claude Code 后,输入以下命令验证:

1
2
3
4
5
# 查看已安装的 MCP 服务器
claude mcp list

# 查看 MCP 服务器详情
claude mcp get chrome-devtools

如果看到 chrome-devtools 在列表中,说明安装成功!


五、使用实战:从零开始

5.1 基础操作示例

安装成功后,你可以直接在 Claude Code 中用自然语言操控浏览器。

示例 1:打开网页并截图

1
请打开 https://example.com,然后截取整个页面的截图

AI 会自动调用 MCP 工具:

  1. browser_navigate - 打开网页
  2. browser_screenshot - 截取屏幕

示例 2:提取页面内容

1
打开 https://news.ycombinator.com,获取首页所有新闻标题

AI 会:

  1. 打开 Hacker News
  2. 用 DOM 选择器提取标题元素
  3. 返回标题列表

示例 3:自动化表单填写

1
打开 https://example.com/login,填写用户名 "test@example.com",密码 "password123",然后点击登录按钮

5.2 调试实战

示例 4:检查控制台错误

1
打开我的项目 http://localhost:3000,检查是否有控制台错误

AI 会查看 console 日志,找出红色错误信息并分析原因。

示例 5:分析网络请求

1
打开 https://myapi.example.com,查看所有 API 请求的响应时间

AI 会:

  1. 捕获网络请求
  2. 分析每个请求的耗时
  3. 找出慢请求并给出优化建议

5.3 性能分析实战

示例 6:页面性能诊断

1
分析 https://mysite.com 的加载性能,找出瓶颈

AI 会:

  1. 录制性能追踪(Performance Trace)
  2. 分析关键指标(FCP、LCP、CLS)
  3. 给出具体优化建议

关键性能指标解释:

指标 全称 含义 理想值
FCP First Contentful Paint 首次内容绘制 < 1.8s
LCP Largest Contentful Paint 最大内容绘制 < 2.5s
CLS Cumulative Layout Shift 累积布局偏移 < 0.1
TTI Time to Interactive 可交互时间 < 3.8s

六、进阶技巧

6.1 连接已有的浏览器实例

如果你已经在调试某个页面,可以让 MCP 连接到现有浏览器:

步骤 1:以调试模式启动 Chrome

Windows:

1
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

Mac:

1
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

步骤 2:修改 MCP 配置

1
2
3
4
5
6
7
8
9
10
11
12
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": [
"-y",
"chrome-devtools-mcp@latest",
"--browser-url=http://127.0.0.1:9222"
]
}
}
}

这样 MCP 会连接到你已有的浏览器,而不是启动新实例。

6.2 禁用数据收集(隐私考量)

Chrome DevTools MCP 默认会收集使用统计数据。如果你在意隐私:

1
"args": ["-y", "chrome-devtools-mcp@latest", "--no-usage-statistics"]

或设置环境变量:

1
export CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS=1

6.3 在 CI/CD 中使用

自动化测试场景建议配置:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": [
"-y",
"chrome-devtools-mcp@latest",
"--headless",
"--no-usage-statistics"
],
"env": {
"CI": "true"
}
}
}
}

七、常见问题排查

7.1 MCP 服务器启动失败

症状: Claude Code 提示 “Failed to start MCP server”

排查步骤:

  1. 检查 Node.js 版本:

    1
    node -v  # 需要 v20.19+
  2. 手动测试 MCP 服务器:

    1
    npx chrome-devtools-mcp@latest
  3. 检查网络连接(npx 需要下载包)

7.2 浏览器连接失败

症状: 提示 “Cannot connect to browser”

解决方案:

  1. 确保 Chrome 已安装且是最新版
  2. 如果使用 --browser-url,确保 Chrome 以调试模式启动
  3. 检查端口是否被占用:
    1
    2
    3
    4
    5
    # Windows
    netstat -ano | findstr 9222

    # Mac/Linux
    lsof -i :9222

7.3 工具调用超时

症状: 操作网页时长时间无响应

可能原因:

  • 页面加载缓慢
  • 网络问题
  • 复杂页面导致操作卡住

建议:

  • 使用 --headless 模式减少资源占用
  • 给 AI 明确的等待指令:”等待页面完全加载后再…”
  • 分步操作,不要一次性执行太多

7.4 Windows 特殊配置

Windows 用户可能遇到启动超时,建议添加环境变量:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"mcpServers": {
"chrome-devtools": {
"command": "cmd",
"args": [
"/c",
"npx",
"-y",
"chrome-devtools-mcp@latest"
],
"env": {
"SystemRoot": "C:\\Windows",
"PROGRAMFILES": "C:\\Program Files"
},
"startup_timeout_ms": 20000
}
}
}

八、最佳实践总结

8.1 使用建议

建议 说明
明确指令 告诉 AI 具体要做什么,不要模糊
分步执行 复杂任务拆成多个步骤
善用等待 让 AI 等待页面加载完成再操作
验证结果 让 AI 截图确认操作是否成功
保存日志 调试时让 AI 保存控制台日志供分析

8.2 安全注意事项

重要提醒: MCP 会将浏览器内容暴露给 AI 助手。

  • 不要在浏览器中打开敏感页面(银行、密码管理器等)
  • 不要填写真实密码或个人信息
  • CI/CD 环境建议禁用使用统计
  • 定期检查 MCP 配置,移除不需要的服务器

8.3 与其他工具对比

工具 类型 优点 适用场景
Chrome DevTools MCP AI+浏览器 AI自主操控、智能分析 调试、分析、自动化
Puppeteer Node.js库 精细控制、成熟稳定 自动化脚本
Selenium 自动化框架 跨浏览器、生态丰富 E2E测试
Playwright 自动化框架 现代、快速、多浏览器 现代Web测试

九、总结

Chrome DevTools MCP 打通了 AI 助手与浏览器之间的壁垒,让 AI 从”只能聊天”进化为”能动手干活”。

核心价值:

  1. 零代码自动化 - 用自然语言操控浏览器
  2. 智能调试 - AI 分析问题,给出解决方案
  3. 性能洞察 - 自动识别性能瓶颈
  4. 开发提效 - 减少手动重复操作

学习路径建议:

1
2
3
4
5
第1天:安装配置,尝试打开网页、截图
第2天:调试实战,检查控制台、网络请求
第3天:自动化测试,填写表单、点击按钮
第4天:性能分析,了解 Web Vitals 指标
第5天:进阶使用,连接已有浏览器、CI集成

参考资料


从抢购算力开始

2026 年,想买个 Coding Plan 太难了。。。

中国的算力紧张,根源在哪?答案很简单:算力要靠显卡,显卡要买英伟达。

显卡是怎么制约算力发展的?为了搞清楚这个问题,我研究了很多方面,但始终绕不开英伟达这家企业。

很多人知道英伟达卖显卡,但不知道 CUDA 是什么。更不知道,CUDA 是英伟达最重要的一段护城河,以及这道护城河是怎么花了二十年一步步挖出来的。

这篇文章,就来聊聊 CUDA 的故事。


一、先搞清楚:CUDA 到底是什么?

CUDA = Compute Unified Device Architecture,翻译过来是”统一计算设备架构”。

听起来很抽象?用一个类比:

类比 说明
GPU 是”肌肉” 专门做大规模并行计算,力量惊人
CUDA 是”大脑” 指挥 GPU 怎么干活,把计算任务调度到各个核心

没有 CUDA,GPU 就只是个画图的机器——只能渲染游戏画面,不能做 AI 训练、科学计算这些”正经事”。

有了 CUDA,GPU 才变成了一台通用计算设备——可以跑任何需要大规模并行计算的程序。

这就是 CUDA 的核心价值:让 GPU 从”画图专用”变成了”万能计算器”。


二、起源:黄仁勋的一场豪赌

2.1 2006 年之前的 GPU 世界

在 2006 年之前,GPU 只有一个用途:打游戏

想用 GPU 做科学计算?你得把计算任务”伪装”成画图任务:

1
2
3
4
5
6
7
你想计算:矩阵乘法
你得告诉 GPU:我要画一堆三角形,颜色就是计算结果

这就像:
你想请厨师做饭
但你只能用"点菜"的方式告诉他
"我要一盘红色的、方形的、味道像矩阵乘法的菜"

这种”骗 GPU 干活”的方式叫 GPGPU(General Purpose GPU)。极其痛苦,效率极低。

2.2 黄仁勋的”押注公司”时刻

2006 年,英伟达 CEO 黄仁勋做了一个决定:

投入 100 亿美元,开发 CUDA 平台

这是什么概念?当时英伟达的市值也就几百亿美元。华尔街疯了:

“你一个卖游戏显卡的公司,为什么要烧钱搞什么通用计算平台?”
“这钱烧下去,什么时候能赚回来?”

黄仁勋的回答很简单:“GPU 不应该只用来打游戏。”

G80 架构(GeForce 8800 GTX)是第一款支持 CUDA 的显卡。它实现了”统一着色器架构”——让 GPU 的所有核心可以执行任意计算任务,而不是只能画三角形。

2.3 漫长的黑暗期

CUDA 发布后,遭遇了长达 6-7 年的冷遇

时间 状态
2006-2008 几乎无人问津,只有少数科研人员用
2008-2010 学术界开始关注,产业界无动于衷
2010-2012 股价低迷,投资者持续质疑

这期间,英伟达默默做了三件事:

  1. 免费开放 CUDA 工具包——任何开发者都可以下载使用
  2. 资助大学教育——让 CUDA 进入计算机课程
  3. 持续迭代硬件——Fermi、Kepler、Maxwell,每一代都优化 CUDA 性能

这就像种树:前六年只浇水不结果,但根系在悄悄扎深。


三、转折:2012 年 AlexNet

2012 年,ImageNet 图像识别竞赛,一个叫 Alex Krizhevsky 的研究生用两块 GTX 580 训练了一个深度神经网络。

结果:碾压全场

对比 AlexNet 传统方法
错误率 15.3% 26%+
训练时间 几周 数月甚至数年
硬件成本 几千美元 数百万美元

关键点:AlexNet 的实现深度依赖 CUDA。

这让全世界 AI 研究者意识到一个公式:

GPU + CUDA + 深度神经网络 = AI 的未来

从这一天开始,CUDA 从”没人用的玩具”变成了”AI 研究的标配”。


四、发展:二十年迭代,从 1.0 到 14.x

CUDA 的发展不是一蹴而就,而是持续二十年的迭代:

1
2
3
4
5
6
7
8
9
CUDA 时间线(2006-2026)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

2006 2012 2016 2022 2024 2026
│ │ │ │ │ │
CUDA 1.0 AlexNet Volta H100 B200 Rubin
│ │ │ │ │ │
│ │ │ │ │ │
冷启动期 AI起飞 生态成熟 大模型爆发 主流出货 下一代
CUDA 版本 年份 关键特性
1.0 2006 基础编程模型
2.0 2008 双精度浮点支持
4.0 2011 动态并行
6.0 2014 统一内存
8.0 2016 Volta 架构优化
10.0 2018 Turing 架构、Tensor Core
11.0 2020 Ampere 架构、多实例 GPU
12.0 2022 Hopper 架构、H100
14.x 2026 Rubin 架构适配

二十年积累,意味着:

维度 2026 年数据
开发者数量 500 万+
CUDA 版本 14.x
算子库数量 3000+
GitHub 项目依赖 数千万
学术论文依赖 95%+

五、护城河:CUDA 是怎么”锁死”竞品的?

5.1 护城河的本质

护城河不只是”技术先进”,而是让竞争对手根本无法入场

CUDA 的护城河是一个多层嵌套的陷阱

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
                    ┌─────────────────────────────────────┐
│ CUDA 护城河层级 │
└─────────────────────────────────────┘

Level 5: 生态网络效应(最难跨越)
├── 全球 500 万开发者,都只会 CUDA
├── 学术论文默认 CUDA,想发 paper 必用 CUDA
└── 开源项目全部绑定 CUDA

Level 4: 软件栈深度(很难)
├── 3000+ 高度优化的算子库
├── cuDNN、cuBLAS、NCCL 等核心库
└── TensorRT、RAPIDS 等工具链

Level 3: 人才知识积累(难)
├── 20 年培养的 GPU 专家
├── 编译器、架构设计团队
└── 性能优化经验

Level 2: 硬件制造差距(困难)
├── 3nm 制程领先 2-3 代
├── HBM3e 内存技术领先
└── NVLink 高速互联

Level 1: 架构设计(相对可追赶)
├── 有公开论文可参考
├── 有人才储备
└── 资金可投入

5.2 软件栈锁定

英伟达的软件栈是一个层层嵌套的体系

1
2
3
4
5
6
7
8
9
10
11
┌─────────────────────────────────────────────┐
│ PyTorch / TensorFlow / JAX 等框架 │ ← 开发者直接接触
├─────────────────────────────────────────────┤
│ TensorRT / RAPIDS / Numba │ ← 性能优化工具
├─────────────────────────────────────────────┤
│ cuDNN / cuBLAS / NCCL / cuSPARSE │ ← 核心计算库
├─────────────────────────────────────────────┤
│ CUDA Runtime / CUDA Driver API │ ← 编程接口
├─────────────────────────────────────────────┤
│ NVIDIA GPU 硆件 │ ← 物理基础
└─────────────────────────────────────────────┘

每一层都只对 NVIDIA 硬件优化

层级 英伟达专有 竞品状态
深度学习框架 PyTorch 对 CUDA 优化最完善 AMD ROCm 支持残缺
计算库 cuDNN 性能碾压其他实现 AMD 没有对标库
通信库 NCCL 多卡通信成熟稳定 AMD 的 RCCL bug 满天飞
开发者 500 万 CUDA 程序员 ROCm 开发者寥寥无几

5.3 开发者锁定

假设你是一家 AI 公司的技术负责人,想迁移到 AMD:

挑战 具体内容
代码资产 你有 50 万行 CUDA 代码,全要重写
人才储备 你的团队精通 CUDA,需要重新培训
基础设施 CI/CD 全基于 NVIDIA GPU,要重建
第三方依赖 开源库都绑定 CUDA,迁移兼容性差
迁移风险 迁移期间 bug 多、性能下降

结论:迁移成本太高,几乎不可能。

这就是开发者锁定的本质:不是 CUDA 技术有多好,而是换一套生态的代价太大。

5.4 学术界锁定

更可怕的是学术界锁定:

1
2
3
4
5
6
AI 研究流程:
论文作者 → 写了 CUDA 代码 → 论文发表 → 代码开源

后续研究者 → 想复现论文 → 必须用 CUDA → 又写了更多 CUDA 代码

循环强化 → 所有论文都默认 CUDA → 学术界被绑定

95% 的 AI 论文默认使用 CUDA。想发 paper、想复现别人的结果、想用开源模型?你必须有 NVIDIA GPU。


六、竞品困境:AMD 和英特尔为什么追不上?

6.1 AMD 的 ROCm

AMD 推出了 ROCm(Radeon Open Compute)试图对标 CUDA:

对比维度 CUDA ROCm
发布时间 2006 2016(晚10年)
开发者数量 500万 估计不足5万
算子库 3000+ 约200个
稳定性 极高 经常出 bug
框架支持 原生级 适配级(残缺)

ROCm 的问题:

  1. 起步太晚——CUDA 已经 10 年积累,ROCm 才开始
  2. 兼容性差——很多 CUDA 代码无法直接迁移
  3. 文档缺失——开发者找不到资料
  4. 社区冷淡——没人愿意贡献代码

6.2 英特尔的 oneAPI

英特尔 2020 年才推出 oneAPI

问题 说明
起步更晚 比 CUDA 晚 14 年
硬件不给力 英特尔 GPU 性能跟不上
开发者不学 没人愿意学一套新 API
市场份额低 几乎没有实际部署

6.3 追赶悖论

更残酷的是:你追上今天的 CUDA,但 CUDA 又进化了。

1
2
3
4
5
6
7
8
9
如果 AMD 今天追上 CUDA 2022 年的水平:
├── CUDA 已经是 2026 年的 14.x 版本
├── NVIDIA 已经发布 Rubin 架构
└── AMD 仍然落后 4 年

追赶速度:
├── NVIDIA 每年迭代一次
├── AMD 每年追赶一点
└── 差距永远存在

七、硬件护城河:不只是软件

很多人以为 CUDA 只是软件,其实硬件也是护城河的一部分:

7.1 制程领先

NVIDIA GPU 制程 发布年份
H100 4nm (TSMC) 2022
B200 4NP (TSMC) 2024
B300 4NP (TSMC) 2025
Rubin R100 3nm (TSMC) 2026H2

台积电最先进的制程,优先给 NVIDIA。

7.2 HBM 内存领先

高端 AI 训练需要高带宽内存(HBM)

GPU 内存规格 带宽
H100 80GB HBM3 3.35 TB/s
B200 192GB HBM3e 8 TB/s
B300 192GB+ HBM3e 8 TB/s+

HBM 由 SK 海力士、三星生产,技术门槛极高。NVIDIA 有优先供应权。

多卡训练需要高速互联:

互联技术 带宽 状态
NVLink 4.0 900 GB/s NVIDIA 专有,成熟稳定
NVLink 5.0 1.8 TB/s 2026 年推出
AMD Infinity Fabric ~400 GB/s 性能落后,稳定性差

八、总结:护城河是怎么挖出来的?

回到开头的问题:CUDA 的护城河是怎么一步步挖出来的?

答案:二十年持续投入 + 多层嵌套锁定。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
第一步:2006 年,投入 100 亿,发布 CUDA
↓ 让 GPU 可以做通用计算

第二步:2006-2012,免费开放 + 大学教育
↓ 培养第一批开发者

第三步:2012 年,AlexNet 证明 GPU+CUDA=AI 未来
↓ 学术界开始绑定 CUDA

第四步:2012-2022,持续迭代 + 构建软件栈
↓ cuDNN、TensorRT、NCCL 等核心库

第五步:2022-2026,大模型爆发
↓ CUDA 成为"空气",无处不在

结果:五层护城河,竞品无法入场

核心逻辑:

护城河类型 形成方式
技术护城河 20 年迭代,3000+ 算子库
生态护城河 500 万开发者,学术界绑定
经济护城河 迁移成本太高,换不起
硬件护城河 制程、HBM、NVLink 领先

一句话总结:

CUDA 的护城河,不是某个天才的设计,而是二十年持续投入的结果。

它像一条河,起初只是一条小溪,没人注意。但英伟达持续挖了二十年,终于变成一条竞品无法跨越的大河。


参考资料

背景

如果你问大模型:”明朝第一位皇帝是谁?”它会自信地回答:”朱元璋。”

但如果你问:”朱元璋的第三任妻子叫什么名字?”它可能回答:”马皇后。”——等等,马皇后是朱元璋的正妻,不是第三任妻子。模型编了一个看似合理、实则错误的答案。

这就是大模型的幻觉(Hallucination):一本正经地胡说八道。

面试时如果只回答”因为它是个概率模型”,会被追问:概率模型怎么了?概率模型就一定会编东西吗?

今天我们从五个层面拆解这个问题,每一层都能让你的理解更有深度。


第一层:训练目标 ≠ 说真话

这是最根本的一层。大模型的训练目标,从一开始就不是”说真话”,而是”预测下一个最可能的 token”。

听起来差不多?差别很大。

训练信号的本质

模型在训练过程中,从未接受过这样的监督信号:

1
2
这句话是事实 ✓
这句话是编的 ✗

它只知道:在这段文本里,前面出现了这些词,下一个词最可能是什么?

1
2
3
4
输入: "明朝开国皇帝是"
训练目标: 预测下一个词是 "朱"(概率最高)
然后是 "元"(基于"朱"之后)
然后是 "璋"(基于"朱元"之后)

模型学的是语言的统计规律,不是世界的真实知识

流畅 ≠ 正确

从训练目标来看,模型追求的是流畅连贯,不是事实正确。

大多数情况下,流畅连贯的文本恰好也是真实的。所以大部分场景下,模型看起来在说真话。

但一旦”说得通”和”说得对”发生冲突:

1
2
3
4
问题: "林黛玉倒拔鲁智深的故事发生在哪一回?"
模型可能回答: "发生在《红楼梦》第X回..."

编造了一个看似合理、实则完全不存在的故事

为什么?因为”林黛玉倒拔鲁智深”本身是个荒谬的问题,但模型会硬着头皮让它”说得通”——生成一个符合语言规律的回答,而不是指出这个问题本身是错的。


第二层:不知道自己不知道什么

人类面对不确定的问题,会有”自知之明”:

1
2
问: "量子力学中薛定谔方程的第三种推导方式是什么?"
人: "我不确定,这个我不太懂。"

但大模型没有这个能力。

训练时的”强制回答”约束

模型训练时被要求必须生成一段通顺的回答,而不是可以选择”我不知道”。

训练数据里很少有这种模式:

1
2
问题: XXX(超出知识范围)
回答: 我不知道 / 这个问题我无法回答

即使有,比例也极低。模型学到的是:有问题 → 必有回答

硬着头皮编

所以,哪怕模型对问题毫无头绪,也会生成一段看似合理的内容:

1
2
3
4
问: "《三体》中章北海的第四个孩子叫什么?"
模型: "章北海的第四个孩子叫章XX..."

语气自信,实则章北海根本没有四个孩子

越是不确定的问题,模型越可能编造——因为它没有”我不确定”这个选项。


第三层:知识是”压缩”的,不是”精确存储”的

大模型不是把所有知识像数据库一样一字不差存下来。

知识的存储方式

模型把海量文本压缩成参数里的统计模式。这个过程类似于:

方式 特点
数据库存储 精确、可检索、一字不差
模型参数存储 模糊、统计性、细节易混淆

就像人记东西,只会记个大概,细节会模糊、会混淆。

压缩带来的问题

模型学到的是模糊的关联、大概的规律,而不是精确的事实

1
2
3
4
5
6
7
模型可能学到的:
- 朱元璋 → 明朝 → 开国皇帝 → 南京 → 马皇后(模糊关联)
- 朱元璋 → 某年某月某日登基(大概规律)

模型不太可能学到的:
- 朱元璋的第三任妻子具体叫什么名字
- 某个具体事件发生的精确日期

一旦需要精准细节(具体日期、数据、人名),就容易张冠李戴、脑补编造


第四层:训练数据本身有”坑”

模型的知识全部来自训练数据。但互联网数据本身充满问题。

数据质量问题

问题类型 例子
错误信息 谣言、虚假新闻
偏见信息 带倾向性的观点
过时信息 2023年的新闻,2026年问就不对了
随意编造 网友随口胡说的内容

这些都是模型的”教材”。模型分不清对错,只会把学到的”错误规律”当真话说。

垃圾进,垃圾出

1
2
3
4
5
6
训练数据中有: "诸葛亮发明了原子弹"(某个网友编的段子)
模型可能学到: 诸葛亮 → 发明 → 原弹(统计关联)
问: "诸葛亮发明了什么?"
答: "诸葛亮发明了原子弹..."

模型把段子当事实了

这不是模型”蠢”,而是训练数据本身就有问题


第五层:生成时的”概率采样”容易跑偏

大模型生成答案,不是逻辑推理,而是按概率”猜”下一个词。

一步步”猜”的问题

每一步都选”最可能的词”,但一步错,步步错

1
2
3
4
5
第1步: 选对了 → 上下文正常
第2步: 选对了 → 继续正常
第3步: 选了个"次优"选项 → 小偏差
第4步: 基于小偏差继续 → 偏差放大
第5步: ... → 大错误

小偏差会累积成大错误,尤其是遇到模糊、冷门、矛盾的问题时。

概率分布越乱,越容易跑偏

1
2
3
常见问题: 概率分布集中 → 选对的概率高
冷门问题: 概率分布分散 → 选错的概率增加
模糊问题: 多个候选概率接近 → 容易选到错误的那个

五层原因的叠加效应

幻觉不是单一原因造成的,而是五层叠加

1
2
3
4
5
6
7
8
9
10
11
12
第1层: 训练目标追求流畅而非正确
↓ 基础设定偏离
第2层: 没有自知之明,不知道边界
↓ 硬着头皮回答
第3层: 知识压缩存储,细节模糊
↓ 精确信息易错
第4层: 训练数据本身有错
↓ 学到错误内容
第5层: 概率采样容易跑偏
↓ 小错累积成大错

最终输出: 一本正经胡说八道

如何缓解幻觉?

了解了原因,才能针对性地解决。

用户层面的技巧

技巧 作用
追问细节 让模型暴露不确定的地方
要求引用来源 逼迫模型承认”不知道来源”
设置温度参数为 0 减少随机性,让模型更保守
明确告知”如果不知道就说不知道” 给模型一个”放弃”的选项

技术层面的方案

方案 原理
RAG(检索增强生成) 先检索真实资料,再基于资料回答
知识图谱 grounding 把回答锚定到可验证的知识节点
多模型交叉验证 让多个模型回答同一问题,对比差异
置信度输出 让模型输出对答案的置信程度
事实核查模块 对模型的回答做二次验证

这些方案各有优劣,但核心思路都是:引入外部真实信息,弥补模型内部的缺陷


总结

大模型”一本正经胡说八道”,不是它故意骗你,也不是它笨,而是底层设计、训练目标、知识存储、数据质量、生成机制五层原因叠加的必然结果

用一个公式概括:

1
幻觉 = 训练目标偏差 + 无自知之明 + 知识压缩 + 数据污染 + 概率跑偏

理解了这一点,你就会明白:大模型是一个流畅的语言生成器,不是精准的事实数据库

用模型时,把它当作一个能快速整理思路、启发想法的助手,而不是权威的知识来源。关键事实,还是要自己核实。


参考资源

背景

“Function Calling 的原理是什么?”,很多人的理解是这样的:

“模型读懂了用户的意图,判断出需要调用工具,然后决定生成一段调用指令……”

听起来很合理?但实际上,这些词——读懂判断决定——都是危险的词

为什么危险?因为它们暗示模型有某种”理解”和”决策”能力,仿佛模型真的在”思考”。但大模型的本质从来没变过:Next Token Prediction(预测下一个词)

Function Calling 并没有引入什么神秘的”推理机制”,它只是让模型学会了在特定情况下切换输出格式——从自然语言切换成结构化的 JSON。

今天我们就来拆解 Function Calling 的底层原理,看看模型到底是怎么”学会”调用工具的。


一、核心原理:没有魔法,还是预测

先说结论:Function Calling 没有引入任何新的推理机制,底层仍然是 Next Token Prediction。

1.1 模型到底在做什么?

无论是否启用 Function Calling,模型的计算过程都是一样的:

1
输入 → Transformer 计算 → 在整个词表上做概率分布 → 采样下一个 Token

区别只在于:启用 Function Calling 后,模型的词表里多了几个特殊 Token,训练数据里多了”工具调用”的样本

1.2 一个形象的比喻

想象你训练了一只鹦鹉,它会模仿人类说话:

  • 普通模式:你教它说”你好”、”谢谢”、”再见”,它学会在合适场合说这些话
  • Function Calling 模式:你额外教它一套”暗号”,比如听到”几点了”就说 [CALL:get_time]

鹦鹉并不知道”几点了”是什么意思,也不知道 get_time 真的会获取时间。它只是学会了:听到 X,就说 Y

Function Calling 的本质也是这样:模型学会了在特定上下文下,输出特定格式的文本——只是这个文本恰好是 JSON 格式的工具调用指令。


二、两阶段训练:如何教会模型”调用工具”

模型是怎么学会 Function Calling 的?主要通过两个阶段的训练。

2.1 SFT 阶段(监督微调)

这个阶段,模型通过大量标注样本,学会三件事:

学习内容 训练样本示例
什么时候切换输出模式 用户问”今天天气怎么样?” → 模型输出 [tool_call] 开始标签
怎么写调用指令 [tool_call]{"name": "get_weather", "args": {"city": "北京"}}[tool_call_end]
怎么处理工具返回结果 工具返回 {"temp": 25, "condition": "晴"} → 模型输出”今天北京天气晴朗,气温25度”

训练数据的结构大致如下:

1
2
3
4
5
6
7
8
{
"messages": [
{"role": "user", "content": "今天北京天气怎么样?"},
{"role": "assistant", "content": "[tool_call]{\"name\": \"get_weather\", \"args\": {\"city\": \"北京\"}}[/tool_call]"},
{"role": "tool", "content": "{\"temp\": 25, \"condition\": \"晴\"}"},
{"role": "assistant", "content": "今天北京天气晴朗,气温25度。"}
]
}

模型通过大量这样的样本,学会了一个模式匹配

1
用户问题涉及"可调用的工具" → 输出 [tool_call] → JSON 格式的调用指令

2.2 RL 阶段(强化学习)

SFT 阶段学会了”基本操作”,但还有很多边界情况需要精调:

边界情况 RL 阶段的优化
该调工具时没调 增加奖励,强化正确行为
不该调工具时调了 减少奖励,抑制错误行为
参数填错 调整参数生成的准确性
调用错工具 优化工具选择的准确性

这个阶段的核心是:让模型学会”分寸感”——知道什么时候该调用,什么时候不该调用。


三、特殊 Token 的作用:给外部系统的信号

Function Calling 的关键设计之一,是引入了特殊 Token

3.1 什么是特殊 Token?

特殊 Token 是专门添加到词表中的”标记”,比如:

1
2
3
[tool_call]     → 工具调用开始
[/tool_call] → 工具调用结束
[tool_result] → 工具返回结果

这些 Token 不是普通的文本,而是专门设计的信号

3.2 为什么需要特殊 Token?

如果没有特殊 Token 有了特殊 Token
模型输出 get_weather(北京) 模型输出 [tool_call]{"name":"get_weather"}[/tool_call]
外部系统需要解析自然语言 外部系统只需检测 [tool_call] 标签
解析容易出错、歧义 解析简单、确定性高

特殊 Token 的本质作用:给外部系统一个确定性的信号。

当模型输出 [tool_call] 时,外部系统就知道:接下来要截获这段文本,解析 JSON,执行调用,然后把结果返回给模型。

3.3 不同厂商的特殊 Token 设计

厂商 开始标签 结束标签 特点
OpenAI <function_call> </function_call> XML 风格
Claude <tool_use> </tool_use> XML 风格
某些国产模型 [TOOL_CALL] [/TOOL_CALL] 方括号风格

虽然形式不同,但核心逻辑一样:给外部系统一个明确的”截获点”


四、推理过程:概率如何决定输出

让我们看看模型在推理时到底发生了什么。

4.1 整个词表上的概率分布

模型在生成每个 Token 时,会在整个词表上计算概率分布。假设词表有 5 万个 Token,模型会计算每个 Token 的”可能性”:

1
2
3
4
5
6
7
8
9
用户输入: "今天北京天气怎么样?"

Token 概率分布(简化示例):
- "今天" : 0.15
- "北京" : 0.08
- "天气" : 0.12
- [tool_call] : 0.45 ← 最高!
- "我" : 0.05
- ...

在这个例子中,[tool_call] 的概率最高,所以模型会输出它。

4.2 上下文如何影响概率

上下文会强烈影响概率分布

1
2
3
4
5
6
7
8
上下文 1: 用户问"今天北京天气怎么样?" + 工具列表包含 get_weather
→ [tool_call] 概率飙升 → 输出工具调用

上下文 2: 用户问"今天北京天气怎么样?" + 工具列表为空
→ "今天" 概率最高 → 输出自然语言回答

上下文 3: 用户问"你好"
→ [tool_call] 概率很低 → 输出自然语言

这就是为什么工具描述很重要:工具描述会被注入到上下文中,”暗示”模型在什么情况下应该调用什么工具。

4.3 概率飙升的机制

可以把这个过程类比为:

1
2
3
4
模型就像一个"概率调节器":
- 工具描述 = "暗示信号"
- 用户问题 = "触发条件"
- 当两者匹配 → [tool_call] 的概率被"推高"

模型并没有”决定”调用工具,只是概率计算的结果恰好是 [tool_call]


五、外部执行:模型只生成,不执行

这是一个关键概念:模型本身不执行函数,只生成文本。

5.1 完整的执行流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
┌─────────────────────────────────────────────────────────────┐
│ 用户提问 │
│ "今天北京天气怎么样?" │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ 大模型生成 │
│ 输出: [tool_call]{"name":"get_weather"}[/tool_call]│
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ 外部系统截获 │
│ 检测到 [tool_call] → 解析 JSON → 执行函数 │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ 函数返回结果 │
│ {"temp": 25, "condition": "晴"} │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ 结果注入回上下文 │
│ 模型看到工具结果 → 生成最终回答:"今天北京天气晴朗..." │
└─────────────────────────────────────────────────────────────┘

5.2 为什么设计成外部执行?

如果模型内部执行 外部执行的设计
模型需要”知道”所有工具的实现细节 模型只需”知道”工具的描述和参数格式
新增工具需要重新训练模型 新增工具只需更新描述,无需重训练
安全风险:模型可能执行危险操作 外部系统可以做权限控制、审计
无法处理实时数据 外部系统可以查询最新数据

外部执行的核心优势:模型只负责”说”,外部系统负责”做”。


六、四种失败模式

Function Calling 不是万能的,模型会犯错。常见的失败模式有四种:

6.1 调用错工具

1
2
3
4
5
用户: "帮我查一下明天的股票行情"
工具列表: [get_weather, send_email, search_web]

模型输出: [tool_call]{"name": "get_weather", "args": {...}}[/tool_call]
↑ 应该调用 search_web,却调用了 get_weather

原因:工具描述不够清晰,或者模型对工具功能的理解有偏差。

6.2 参数填错

1
2
3
4
5
用户: "帮我订一张明天从北京到上海的机票"
工具: book_ticket(from_city, to_city, date)

模型输出: [tool_call]{"name": "book_ticket", "args": {"from_city": "上海", "to_city": "北京"}}
↑ 起点终点搞反了

原因:模型对参数的”填充”是基于上下文的语义理解,而不是精确的逻辑推理。

6.3 该调工具时没调

1
2
3
4
用户: "现在几点了?"
工具列表: [get_current_time]

模型输出: "现在是2024年..." ← 编造了一个答案,没有调用工具

原因:工具描述不够突出,或者模型”自信”地认为自己知道答案。

6.4 不该调工具时调了

1
2
3
4
5
用户: "讲一个关于时间的故事"
工具列表: [get_current_time]

模型输出: [tool_call]{"name": "get_current_time"}[/tool_call]
↑ 用户只是想听故事,不需要真的查时间

原因:模型”过度积极”,看到”时间”相关词汇就触发工具调用。

6.5 失败模式总结

失败模式 典型原因 缓解方法
调用错工具 工具描述不清晰 优化工具描述,增加示例
参数填错 语义理解偏差 参数校验,增加约束
该调没调 模型过度自信 提示词引导,RL 优化
不该调调了 过度积极触发 工具描述加”适用场景”

七、不同厂商的差异

虽然 Function Calling 的核心原理相同,但不同厂商在实现上有差异:

7.1 特殊 Token 设计

厂商 设计风格 特点
OpenAI XML 风格标签 可读性好,易于解析
Claude XML 风格标签 支持多工具并行调用
部分国产模型 方括号风格 与系统提示词更统一

7.2 工具描述注入方式

方式 说明 优点 缺点
System Prompt 注入 工具描述放在 System Prompt 灵活,易于调试 占用上下文
特殊字段注入 API 有专门的 tools 字段 结构清晰,便于管理 需要解析
混合方式 部分在 System Prompt,部分在 API 兼顾灵活和结构 可能冲突

7.3 并行调用支持

1
2
3
4
5
6
7
8
9
10
11
12
13
# OpenAI:支持并行调用多个工具
response = client.chat.completions.create(
model="gpt-4",
messages=[...],
tools=[
{"type": "function", "function": {"name": "get_weather"}},
{"type": "function", "function": {"name": "get_stock"}}
]
)
# 模型可以一次性输出多个工具调用

# 部分模型:只支持串行调用
# 需要先调用一个工具,返回结果后,再决定是否调用下一个

7.4 强制/禁止调用控制

控制方式 说明
tool_choice: "auto" 模型自动决定是否调用工具(默认)
tool_choice: "required" 强制模型必须调用某个工具
tool_choice: "none" 禁止模型调用工具
tool_choice: {"name": "xxx"} 强制调用指定的工具

八、总结:理解 Function Calling 的五个要点

最后,用五个要点总结 Function Calling 的底层原理:

要点一:没有新机制

Function Calling 没有引入新的推理机制,底层仍然是 Next Token Prediction。

模型只是学会了在特定上下文下,输出特定格式的文本——只是这个文本恰好是 JSON 格式的工具调用指令。

要点二:两阶段训练

1
2
SFT 阶段:教会模型"基本操作"(何时调用、怎么写、怎么处理结果)
RL 阶段:精调"分寸感"(边界情况的处理)

要点三:特殊 Token 是信号

特殊 Token 不是给模型”理解”的,而是给外部系统截获的确定性信号

要点四:外部执行

模型只生成文本,不执行函数。 外部系统负责:截获指令 → 执行调用 → 返回结果。

要点五:概率决定一切

模型没有”决定”调用工具,只是概率计算的结果恰好是 [tool_call]。上下文(包括工具描述)会影响概率分布,从而影响输出。


写在最后

理解 Function Calling 的底层原理,更重要的是:

  1. 知道它的局限性:模型会犯错,需要外部校验
  2. 知道怎么优化:工具描述、提示词设计、参数校验
  3. 知道怎么调试:当模型调用错误时,从概率角度分析原因

“Function Calling 的底层原理是 Next Token Prediction,没有引入新的推理机制。模型通过 SFT 和 RL 两阶段训练,学会了在特定上下文下输出特殊 Token 标记的 JSON 格式调用指令。特殊 Token 是给外部系统的信号,外部系统负责截获、执行和返回结果。”

这个回答,比”模型读懂了意图、判断需要调用工具、决定生成调用指令”要准确得多。


参考资源

一、写在前面:为什么需要 Superpowers?

你有没有遇到过这样的场景:

  • 让 AI 帮你写代码,它一上来就开始”输出”,完全不考虑你的真实需求
  • AI 写的代码看似没问题,但测试一跑就崩,因为它根本没写测试
  • AI “自主工作”了半小时,结果偏离了原需求十万八千里
  • 多个功能并行开发,AI 把代码混在一起,最后连回滚都困难

Superpowers 就是解决这些问题的”流程管家”。它不是让 AI 更聪明,而是让 AI 更靠谱——先规划、再测试、再实现、再审查,像真正工程师一样工作。


二、Superpowers 是什么?

2.1 一句话定义

Superpowers 是由 Jesse Vincent(Perl 专家、Markdown 发明者之一)开发的软件开发工作流系统,通过一系列”技能(Skills)”让 AI 编码助手遵循严格的工程流程。

2.2 核心理念

打个比方:

没有 Superpowers 有 Superpowers
AI 像是个”热情但冲动的新手”——拿到任务就写代码,写完就交 AI 像是个”老练的资深工程师”——先问清楚需求,写测试,再实现,最后审查
容易偏离需求 强制按计划执行
测试是”事后补的” 测试是”先写的”(TDD)
一个分支干所有事 Git Worktree 隔离开发

2.3 支持的 AI 工具

工具 安装方式
Claude Code /plugin install superpowers@claude-plugins-official
Cursor /add-plugin superpowers
GitHub Copilot CLI copilot plugin install superpowers
Gemini CLI gemini extensions install
Codex CLI 手动配置(见后文)
OpenCode 手动配置

三、核心工作流程详解

3.1 七步流程

Superpowers 强制 AI 遵循以下流程:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
┌──────────────────────────────────────────────────────────────────────┐
│ Superpowers 工作流程 │
├──────────────────────────────────────────────────────────────────────┤
│ │
│ 1. brainstorming (头脑风暴) │
│ └─► AI 不直接写代码,先问你"到底想做什么" │
│ └─► 通过苏格拉底式提问,提炼出清晰的设计文档 │
│ │
│ 2. using-git-worktrees (创建隔离工作空间) │
│ └─► 自动创建新分支 + Git Worktree │
│ └─► 确保开发环境干净、可回滚 │
│ │
│ 3. writing-plans (编写计划) │
│ └─► 将设计拆成 2-5 分钟的小任务 │
│ └─► 每个任务包含:文件路径、代码、验证步骤 │
│ │
│ 4. subagent-driven-development (子代理执行) │
│ └─► 每个任务派发一个新的子代理 │
│ └─► 主代理审查子代理的工作 │
│ └─► 可连续自主工作数小时 │
│ │
│ 5. test-driven-development (强制 TDD) │
│ └─► RED: 先写失败的测试 │
│ └─► GREEN: 写最少代码让测试通过 │
│ └─► REFACTOR: 优化代码 │
│ └─► 如果代码先于测试写了,会被删除! │
│ │
│ 6. requesting-code-review (代码审查) │
│ └─► 每个任务完成后自动审查 │
│ └─► 两阶段审查:规格合规 + 代码质量 │
│ └─► 关键问题会阻塞进度 │
│ │
│ 7. finishing-a-development-branch (完成分支) │
│ └─► 验证所有测试通过 │
│ └─► 提供:合并 / PR / 保留 / 丢弃选项 │
│ └─► 清理 Worktree │
│ │
└──────────────────────────────────────────────────────────────────────┘

3.2 为什么这套流程有效?

问题 1:AI 容易”跑偏”

传统 AI 编码:

1
2
3
4
5
用户:帮我加个登录功能
AI:好的,开始写代码...
(30分钟后)
AI:登录功能写好了,还顺便加了注册、找回密码、OAuth...
用户:??我只想要个简单的登录啊

有 Superpowers:

1
2
3
4
5
6
7
8
9
用户:帮我加个登录功能
AI (brainstorming):让我先理解一下:
- 登录方式是什么?账号密码?OAuth?
- 需要记住登录状态吗?多久?
- 安全要求是什么?
用户:账号密码登录,记住 7 天,简单安全就行
AI:好的,我来写设计文档,你确认后再动手
(用户确认后)
AI:现在开始实现,每个任务都会按计划执行

问题 2:AI 不写测试

传统 AI 编码:

1
2
3
4
AI:功能写完了!
用户:测试呢?
AI:呃...我补一下
(补的测试可能根本测不到关键逻辑)

有 Superpowers(强制 TDD):

1
2
3
4
5
AI:现在要实现登录验证
AI:先写测试(RED)→ 测试失败 ✓
AI:再写代码(GREEN)→ 测试通过 ✓
AI:重构优化(REFACTOR)→ 测试仍通过 ✓
AI:继续下一个任务

问题 3:多功能开发混乱

传统方式:

1
2
3
4
5
main 分支上同时开发 3 个功能
功能 A 改了文件 X
功能 B 也改了文件 X
功能 C 又改了文件 X
→ 冲突灾难

有 Superpowers(Git Worktree):

1
2
3
4
功能 A → worktree/feature-a/ (独立目录)
功能 B → worktree/feature-b/ (独立目录)
功能 C → worktree/feature-c/ (独立目录)
→ 完全隔离,互不影响


四、安装配置实战

4.1 Claude Code 安装(推荐)

方式一:官方插件市场(最简单)

1
2
# 在 Claude Code 中执行
/plugin install superpowers@claude-plugins-official

方式二:第三方市场

1
2
3
4
5
# 先注册市场
/plugin marketplace add obra/superpowers-marketplace

# 再安装插件
/plugin install superpowers@superpowers-marketplace

验证安装:

1
2
3
4
# 查看已安装插件
/plugin list

# 应该看到 superpowers

4.2 Cursor 安装

在 Cursor Agent 聊天中:

1
/add-plugin superpowers

或者在插件市场搜索 “superpowers”。

4.3 GitHub Copilot CLI 安装

1
2
3
4
5
# 注册市场
copilot plugin marketplace add obra/superpowers-marketplace

# 安装插件
copilot plugin install superpowers@superpowers-marketplace

4.4 Codex CLI 手动安装

Codex 目前没有插件市场,需要手动配置:

步骤 1:获取技能文件

1
2
3
4
5
6
# 克隆仓库
git clone https://github.com/obra/superpowers.git

# 复制技能到 Codex 目录
mkdir -p ~/.codex/skills
cp -r superpowers/skills/* ~/.codex/skills/

步骤 2:配置 Codex

创建或编辑 ~/.codex/config.json

1
2
3
{
"skillsDirectory": "~/.codex/skills"
}

步骤 3:验证

启动 Codex 后,技能会自动加载。

4.5 Gemini CLI 安装

1
2
3
4
5
# 安装扩展
gemini extensions install https://github.com/obra/superpowers

# 更新
gemini extensions update superpowers

4.6 更新插件

1
2
3
4
5
6
7
8
# Claude Code
/plugin update superpowers

# Copilot CLI
copilot plugin update superpowers

# Gemini CLI
gemini extensions update superpowers

五、使用实战:从零开始

5.1 触发技能

Superpowers 的技能会自动触发。你不需要特殊命令,只需要用自然语言描述需求。

示例:启动一个新功能

1
我想给博客系统加一个评论功能,支持用户登录后评论

AI 会自动调用 brainstorming 技能:

1
2
3
4
5
6
7
8
AI:让我先理解你的需求...

问题 1:评论需要审核吗?还是直接发布?
问题 2:评论可以回复吗?支持嵌套?
问题 3:评论内容有什么限制?字数、格式?
问题 4:需要通知博主吗?邮件?站内?

请逐一回答,我会根据你的回答设计功能。

5.2 头脑风暴阶段

你的回答:

1
2
3
4
评论不需要审核,直接发布
支持回复,但不嵌套(最多一层)
评论最多 500 字,不能发链接
不需要通知

AI 会生成设计文档:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
## 评论功能设计文档

### 核心需求
- 用户登录后可评论
- 评论直接发布,无需审核
- 支持回复评论(一层)

### 技术方案
- 数据表:comments (id, user_id, post_id, content, parent_id, created_at)
- API:POST /comments, GET /comments/:post_id
- 前端:评论框 + 评论列表 + 回复按钮

### 验收标准
- 登录用户可发表评论
- 可回复他人评论
- 评论字数限制 500 字
- 不允许发送链接

你确认后,AI 进入下一阶段。

5.3 Git Worktree 阶段

AI 会自动:

1
2
3
4
5
6
7
8
9
10
11
12
# 创建新分支
git checkout -b feature/comments

# 创建 Worktree(独立工作目录)
git worktree add .claude/worktrees/feature-comments feature/comments

# 在 Worktree 中初始化环境
cd .claude/worktrees/feature-comments
npm install # 或其他项目初始化命令

# 验证测试基线
npm test # 确保当前测试都通过

Worktree 的好处:

1
2
3
4
5
6
你的主项目目录:     /projects/my-blog/
评论功能 Worktree: /projects/my-blog/.claude/worktrees/feature-comments/

两个目录完全独立!
你可以在主目录继续其他工作
AI 在 Worktree 专心开发评论功能

5.4 编写计划阶段

AI 会把设计拆成小任务:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
## 实现计划

### 任务 1:创建评论数据模型 (预计 3 分钟)
- 文件:`src/models/comment.js`
- 代码:定义 Comment schema
- 验证:模型可正确创建实例

### 任务 2:添加评论 API (预计 5 分钟)
- 文件:`src/routes/comments.js`
- 代码:POST /comments, GET /comments/:post_id
- 验证:API 测试通过

### 任务 3:评论前端组件 (预计 10 分钟)
- 文件:`src/components/CommentBox.jsx`, `src/components/CommentList.jsx`
- 代码:评论输入框、评论列表、回复按钮
- 验证:组件渲染正确,可交互

### 任务 4:字数限制和链接过滤 (预计 3 分钟)
- 文件:`src/utils/commentValidator.js`
- 代码:验证函数
- 验证:超过 500 字拒绝,包含链接拒绝

### 任务 5:集成测试 (预计 5 分钟)
- 文件:`tests/comment.test.js`
- 代码:完整流程测试
- 验证:测试通过

任务粒度原则:

  • 每个任务 2-5 分钟
  • 明确的文件路径
  • 验证步骤

5.5 子代理执行阶段

这是 Superpowers 的核心亮点:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
┌─────────────────────────────────────────────────────────────┐
│ 子代理驱动开发 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 主代理 (你对话的 AI) │
│ │ │
│ ├──► 派发子代理 1 → 执行任务 1 (创建模型) │
│ │ │ │
│ │ └──► 完成后返回结果 │
│ │ │
│ ├──► 主代理审查:符合设计?代码质量? │
│ │ │
│ ├──► 派发子代理 2 → 执行任务 2 (添加 API) │
│ │ │ │
│ │ └──► 完成后返回结果 │
│ │ │
│ ├──► 主代理审查... │
│ │ │
│ └──► 继续执行... │
│ │
│ 优势: │
│ - 每个任务用"新鲜"的子代理,无上下文污染 │
│ - 主代理审查,确保质量 │
│ - 可连续自主工作数小时 │
│ │
└─────────────────────────────────────────────────────────────┘

你的体验:

1
2
3
4
5
6
7
8
AI:开始执行任务 1...
AI:任务 1 完成,审查中...
AI:审查通过 ✓,继续任务 2...
AI:任务 2 完成,审查中...
AI:发现一个小问题,已修复 ✓
AI:继续任务 3...
(你可以去喝咖啡了)
AI:所有任务完成!

5.6 TDD 阶段(强制)

Superpowers 的 TDD 是真正的 RED-GREEN-REFACTOR:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// 步骤 1:RED - 先写失败的测试
describe('CommentValidator', () => {
it('should reject comment longer than 500 chars', () => {
const longComment = 'a'.repeat(501);
expect(validateComment(longComment)).toBe(false);
});
});

// 运行测试 → 失败 ✓ (因为 validateComment 还不存在)

// 步骤 2:GREEN - 写最少代码让测试通过
function validateComment(content) {
if (content.length > 500) return false;
return true;
}

// 运行测试 → 通过 ✓

// 步骤 3:REFACTOR - 优化代码
function validateComment(content) {
const MAX_LENGTH = 500;
const LINK_PATTERN = /https?:\/\/\S+/;

if (content.length > MAX_LENGTH) return false;
if (LINK_PATTERN.test(content)) return false;
return true;
}

// 运行测试 → 仍通过 ✓

如果 AI 先写了代码再写测试?

1
2
AI 会删除代码,重新从测试开始写!
这是强制的,不是建议。

5.7 代码审查阶段

每个任务完成后,主代理会审查:

审查维度:

维度 检查内容
规格合规 是否符合设计文档?
代码质量 可读性、命名、结构
测试覆盖 测试是否充分?
安全性 有无安全漏洞?

审查结果:

1
2
3
4
5
6
7
8
审查报告:

✓ 规格合规:符合设计文档
⚠ 代码质量:变量命名可优化(comment → userComment)
✓ 测试覆盖:覆盖了主要场景
✓ 安全性:无明显问题

建议:优化变量命名后继续

关键问题会阻塞进度:

1
2
❌ 发现关键问题:API 缺少权限验证
→ 必须修复后才能继续

5.8 完成分支阶段

所有任务完成后:

1
2
3
4
5
6
7
8
9
10
AI:所有任务完成!验证测试...
AI:所有测试通过 ✓

请选择下一步:
[1] 合并到主分支
[2] 创建 Pull Request
[3] 保留分支(暂不合并)
[4] 丢弃所有更改

你的选择?

选择后,AI 会:

1
2
3
4
5
6
7
# 如果选择合并
git checkout main
git merge feature/comments
git worktree remove .claude/worktrees/feature-comments

# 如果选择创建 PR
gh pr create --title "Add comment feature" --body "..."

六、与 GitHub SpecKit 的对比

6.1 两者是什么关系?

SuperpowersGitHub SpecKit 都是”规范驱动开发”的工具,但理念和实现方式不同。

特性 Superpowers GitHub SpecKit
开发者 Jesse Vincent(独立开发者) GitHub 官方
形态 Skills 插件系统 CLI + Skills + Extensions 生态
核心理念 流程至上 - 强制 TDD、强制审查 规范至上 - spec 成为可执行文档
安装方式 /plugin install uv tool install specify-cli
项目宪法 /speckit.constitution 创建
产出文件 动态生成 固定:spec.md, plan.md, tasks.md
TDD 强制 RED-GREEN-REFACTOR 推荐但不强制
Git Worktree 自动创建 无内置
子代理执行 内置 subagent-driven 通过扩展实现
可视化 UI VS Code 扩展支持
外部集成 有限 Jira、Azure DevOps、Linear 等 40+ 扩展

6.2 核心哲学差异

Superpowers:流程至上

1
2
3
4
5
6
7
8
核心理念:"让 AI 不犯错误"

方式:强制工程流程
- 不写测试就不能写代码
- 不审查就不能继续
- 不隔离就不能开发

适合:个人开发者、追求代码质量

SpecKit:规范至上

1
2
3
4
5
6
7
8
核心理念:"让规范成为第一性原理"

方式:规范可执行
- spec.md 直接生成代码
- 规范是"活的",不是文档
- 专注于"做什么",而非"怎么做"

适合:团队协作、需要外部集成

6.3 工作流对比

Superpowers 流程:

1
2
3
需求 → 头脑风暴 → Worktree → 计划 → 子代理执行 → TDD → 审查 → 完成分支
↑ ↑ ↑ ↑ ↑ ↑
问清楚 隔离环境 拆任务 自动执行 强制 质量保证

SpecKit 流程:

1
2
3
宪法 → Specify → Plan → Tasks → Implement
↑ ↑ ↑ ↑ ↑
原则 需求 技术 任务 执行

6.4 SpecKit 的独特优势

1. 项目宪法

1
2
3
4
5
# 定义项目原则
/speckit.constitution Create principles focused on:
- Code quality: clean code, no duplication
- Testing: unit tests required for all logic
- Performance: response time < 200ms

这会生成一个”宪法文件”,指导所有后续开发。

2. 丰富的扩展生态

扩展 功能
spec-kit-jira 同步到 Jira
spec-kit-review 代码审查
spec-kit-qa QA 测试
spec-kit-ship 自动发布
superpowers-bridge 将 Superpowers 集成到 SpecKit!

3. 预设系统

可以自定义术语和模板:

1
2
3
4
5
6
7
8
{
"name": "pirate-speak",
"templates": {
"spec.md": "Voyage Manifest",
"plan.md": "Battle Plan",
"tasks.md": "Crew Assignments"
}
}

6.5 Superpowers 的独特优势

1. 强制 TDD

1
2
3
这是最大的区别。
SpecKit 推荐 TDD,但 Superpowers 强制 TDD。
如果你先写代码再写测试,代码会被删除。

2. Git Worktree 隔离

1
2
3
4
每个功能在独立目录开发:
- 不影响主项目
- 可以并行开发多个功能
- 回滚简单(删除 worktree 即可)

3. 子代理驱动

1
2
3
4
每个任务派发新的子代理:
- 无上下文污染
- 主代理审查质量
- 可连续自主工作数小时

6.6 可以一起用吗?

可以! 社区已经创建了 superpowers-bridge 扩展:

1
2
3
4
5
# 在 SpecKit 项目中安装
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 安装 superpowers-bridge 扩展
# (详见扩展文档)

这样你可以:

  • 用 SpecKit 管理规范和外部集成
  • 用 Superpowers 的 TDD、Worktree、子代理执行

七、最佳实践与适用场景

7.1 适用场景建议

场景 推荐
个人开发者,追求代码质量 Superpowers
企业团队,需要外部集成 SpecKit
已有完善规范流程 SpecKit(可定制扩展)
需要长时间自主运行 Superpowers(子代理可工作数小时)
多功能并行开发 Superpowers(Git Worktree)
两者都需要 SpecKit + superpowers-bridge

7.2 使用 Superpowers 的建议

建议 1:让 AI 问清楚再开始

1
2
3
4
不要急着说"开始写代码"
等 AI 完成头脑风暴
仔细阅读设计文档
确认后再说"开始实现"

建议 2:任务粒度要小

1
2
3
4
5
6
7
好的任务:2-5 分钟,一个文件
不好的任务:"实现整个评论功能"

小任务的好处:
- 更容易审查
- 更容易回滚
- 更容易并行

建议 3:关注审查报告

1
2
3
不要忽略审查报告中的警告
即使是"建议优化"
让 AI 修复后再继续

建议 4:并行开发时用 Worktree

1
2
3
4
5
6
如果你要同时开发 3 个功能:
功能 A → 让 AI 创建 worktree/feature-a
功能 B → 让 AI 创建 worktree/feature-b
功能 C → 让 AI 创建 worktree/feature-c

完全隔离,不会冲突

7.3 使用 SpecKit 的建议

建议 1:先写宪法

1
/speckit.constitution Define project principles first

宪法会指导所有后续开发,相当于”项目宪法”。

建议 2:选择合适的扩展

1
2
3
需要 Jira 集成?→ spec-kit-jira
需要代码审查?→ spec-kit-review
需要自动发布?→ spec-kit-ship

建议 3:利用社区预设

1
2
3
4
不想自己配置?
用社区预设:
- Agent Teams Lite(多代理)
- Pirate Speak(有趣模板)

八、常见问题

Q1: Superpowers 和 SpecKit 可以同时用吗?

可以。 安装 superpowers-bridge 扩展即可。

Q2: Superpowers 会让我写代码变慢吗?

短期内可能变慢(因为要先规划、先写测试),但长期会更快(因为减少返工)。

Q3: 子代理执行安全吗?

安全。 子代理在隔离环境中执行,主代理审查结果。

Q4: Git Worktree 会占用很多磁盘空间吗?

会占用一些,但完成后会自动清理。 你也可以手动清理:

1
2
git worktree list
git worktree remove <path>

Q5: SpecKit 的扩展稳定吗?

社区扩展由独立开发者维护,GitHub 官方不审核。 使用前建议查看源代码。


九、总结

核心要点

  1. Superpowers 是流程管家:让 AI 遵循严格的工程流程
  2. 核心流程:头脑风暴 → Worktree → 计划 → 子代理 → TDD → 审查 → 完成
  3. 强制 TDD:不写测试就不能写代码
  4. Git Worktree:每个功能在独立目录开发
  5. 子代理执行:每个任务派发新的子代理,主代理审查

与 SpecKit 的核心区别

方面 Superpowers SpecKit
理念 流程至上 规范至上
TDD 强制 推荐
Worktree 自动 无内置
子代理 内置 通过扩展
生态 单一技能库 40+ 扩展

选择建议

1
2
3
追求代码质量、个人开发 → Superpowers
团队协作、外部集成 → SpecKit
两者都需要 → SpecKit + superpowers-bridge

学习路径

1
2
3
4
5
第 1 天:安装 Superpowers,体验头脑风暴
第 2 天:完整走一遍流程,感受 TDD
第 3 天:尝试并行开发(Worktree)
第 4 天:对比 SpecKit,选择适合你的
第 5 天:深入使用,定制你的工作流

参考资料


背景

“在 Multi-Agent 系统中,主 Agent 如何动态派生 Subagent 协同工作?”

这个问题看似简单,但如果你回答”就是多写几个 Prompt,让大模型自己看着办”,可能就差点意思了。

为什么?因为在实际的大模型工程落地中,放任自由就等于系统崩溃

今天我们就来拆解一套能在百万级并发下稳定运行的多智能体架构,看看高手是怎么玩转”分身术”的。


一、核心运转逻辑:主 Agent 不干杂活

假设我们要干个大活,比如”调研过去十年七十五家科技公司的技术路线演进”。这要是让一个 Agent 单干,CPU 非得烧了不可。

高手的设计思路是什么?

主 Agent 自己不动手干杂活,它只负责规划和调度。

1.1 动态大纲:系统的灵魂

主 Agent 接到任务后的第一件事,是生成一个动态大纲(Dynamic Outline)

这个大纲实时记录了:

  • 哪些任务已经查过了
  • 哪些任务正在执行中
  • 哪些任务还没分发下去
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
动态大纲示例:
┌─────────────────────────────────────────────────────┐
│ 任务:调研75家科技公司技术路线演进 │
├─────────────────────────────────────────────────────┤
│ ✅ 已完成: │
│ - 苹果公司技术路线(Subagent-A 完成) │
│ - 谷歌公司技术路线(Subagent-B 完成) │
├─────────────────────────────────────────────────────┤
│ 🔄 进行中: │
│ - 微软公司技术路线(Subagent-C 执行中) │
│ - 亚马逊技术路线(Subagent-D 执行中) │
├─────────────────────────────────────────────────────┤
│ ⏳ 待分发: │
│ - Meta、特斯拉、英伟达...(剩余71家) │
└─────────────────────────────────────────────────────┘

这个大纲就是整个系统的全局唯一真相源,谁领了什么任务、完成进度如何,一目了然。

1.2 delegate_task:派生 Subagent 的工具

主 Agent 手里握着一个核心工具:delegate_task

当它发现大纲里有子任务需要分发时,就调用这个工具,瞬间派生出多个独立的 Subagent。这些小机器人领了任务就并行地去爬网页、读文档了。

1
2
3
4
5
6
主 Agent

├── delegate_task("调研苹果公司") → Subagent-A
├── delegate_task("调研谷歌公司") → Subagent-B
├── delegate_task("调研微软公司") → Subagent-C
└── delegate_task("调研亚马逊") → Subagent-D

在这个过程中,主 Agent 就像指挥家——它不弹琴,只负责看谁拉错了、谁还没开始。

这就是动态派生的核心:主 Agent 负责”想”,Subagent 负责”干”。


二、强制压缩机制:防止上下文爆炸

Subagent 都在外面干活了,问题也跟着来了。

2.1 信息爆炸问题

想象一下,如果 Subagent 把查到的几万字网页原文一股脑全发给主 Agent,会发生什么?

  • 主 Agent 的上下文窗口瞬间爆掉
  • 模型陷入”看了后面忘前面”的尴尬境地
  • Token 费用能让老板直接找你谈话

2.2 解决方案:强制压缩

我们要给 Subagent 下个死命令:回来之前必须自我压缩

1
2
3
4
5
6
Subagent 执行流程:

1. 爬取网页(获取原始内容,可能几万字)
2. 阅读分析(理解内容,提取关键信息)
3. 自我压缩(提炼结论和事实,过滤噪音) ← 关键步骤!
4. 汇报结果(只带回精炼简报)

这样,主 Agent 拿到的永远是精炼简报,它的大脑永远能保持清醒。

这叫”收敛重于发散”——子节点必须负责压缩信息。


三、防止无限繁衍:工程硬约束

接下来这个难点更刺激:无限繁衍问题

有没有人遇到过这种情况:Agent 碰到一个难题解决不了,就开始疯狂”生孩子”,子又生孙、孙又生子……Token 消耗呈指数级爆炸,系统直接死循环。

3.1 两个硬性约束

为了防范这种工程灾难,我们的架构里加了两个硬性约束:

约束类型 具体规则 作用
辈分隔离 只有主 Agent 有派生权,Subagent 严禁再派生 Subagent 扁平化管理,杜绝递归
物理限流 在代码里直接锁死最大并发数(比如20个) 用工程刚性限制模型随机性
1
2
3
4
5
6
7
8
9
10
11
12
13
正确架构(扁平化):
主 Agent
├── Subagent-A
├── Subagent-B
├── Subagent-C
└── Subagent-D(最多20个)

错误架构(嵌套):
主 Agent
└── Subagent-A
└── Subagent-A-1
└── Subagent-A-1-1
└── ...(无限递归,系统崩溃)

这就是”扁平优于嵌套”——严禁递归派生,防止系统失控。

用工程的刚性去限制模型的随机性,这才是老司机的做法。


四、状态冲突解决:大纲即真相

任务一多,Subagent 之间会不会踩脚?

比如:

  • Agent-A 和 Agent-B 都在查同一家公司,重复劳动
  • Agent-A 把 Agent-B 刚写好的结论给覆盖了

这时候,动态大纲就派上用场了。

4.1 任务边界划分

主 Agent 分发任务时,会基于动态大纲做严格的边界划分:

1
2
3
4
5
6
7
8
9
def distribute_tasks(outline):
for task in outline.pending_tasks:
# 检查是否已被其他 Agent 领取
if task not in outline.in_progress:
# 检查是否已完成
if task not in outline.completed:
# 标记为进行中,分配给新 Agent
outline.mark_in_progress(task)
delegate_task(task)

状态必须中心化,大纲才是全局唯一真相源。

每个 Subagent 只知道自己领了什么任务,而主 Agent 通过大纲掌握全局状态,确保大家各走各的路、互不干扰。


五、系统评估:LLM-as-a-Judge

这种动态系统怎么评估好坏?

因为它每次跑的路径都不一样,传统的单元测试基本就失效了。你不能写断言说”第3步必须调用工具A”,因为下次运行可能第2步就调用了。

目前最前沿的方案是 LLM-as-a-Judge

1
2
3
4
5
评估流程:
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 主 Agent │ ──→ │ 最终报告 │ ──→ │ 裁判模型 │
│ 执行任务 │ │ (输出物) │ │ 打分评判 │
└─────────────┘ └─────────────┘ └─────────────┘

简单说,就是请一个更牛的模型来当裁判,让它给主 Agent 产出的最终报告打分:

  • 信息完整性:该调研的是不是都调研了?
  • 逻辑连贯性:结论是不是有理有据?
  • 准确性:引用的事实是不是正确?

通过这种规模化的自动评测,我们才能真正量化改了这个系统是真的变聪明了还是在乱跑


六、总结:构建稳健 Multi-Agent 系统的三原则

构建百万级并发的多智能体系统,靠的绝对不是让模型自由发挥,而是克制的工程约束

记住这三句话:

原则 核心思想 工程手段
收敛重于发散 子节点必须负责压缩信息 强制压缩机制,过滤噪音
扁平优于嵌套 严禁递归派生,防止失控 辈分隔离 + 物理限流
状态必须中心化 大纲是全局唯一真相源 动态大纲统一管理任务状态

在 AI 时代,能写出 Prompt 只是入门;能设计出稳健、可控的工程架构,才是你拿高薪的底气。


写在最后

Multi-Agent 系统的魅力在于:它让大模型从”单打独斗”进化成”团队协作”

但团队的规模越大,管理的复杂度就越高。就像现实中的项目管理一样,没有好的流程和约束,团队就会陷入混乱。

主 Agent 就像项目经理,Subagent 就像团队成员,动态大纲就是项目管理工具。三者协同,才能让系统跑得稳、跑得快。

希望这篇文章能给你带来一些启发。如果你也在做 Agent 相关的工作,欢迎交流讨论!


一、CrewAI 是什么?

官方定义

CrewAI 是一个精简、快速的 Python 框架,用于编排自主 AI 代理(Agent)。它让多个 AI Agent 可以协同工作,像一个团队一样完成复杂任务。

核心特点

特点 说明
独立框架 不依赖 LangChain 或其他框架,从零构建
高性能 比 LangGraph 快 5 倍以上
灵活定制 从高层工作流到底层提示词都可定制
两种模式 Crews(自主协作)+ Flows(精确控制)

与其他框架对比

框架 优点 缺点
CrewAI 简洁、快速、独立 社区相对较新
LangGraph 功能强大 样板代码多、与 LangChain 强耦合
Autogen 对话代理能力强 缺乏流程概念
ChatDev 有流程概念 定制能力有限

适用场景

  • 自动化工作流(报告生成、数据分析)
  • 多角色协作系统(一人公司、虚拟团队)
  • 复杂任务分解与执行
  • AI 驱动的应用开发

二、核心概念

2.1 Agent(代理)

Agent 是 CrewAI 的核心单元,代表一个”角色”。

1
2
3
4
5
6
7
8
9
10
11
from crewai import Agent

agent = Agent(
role="高级数据分析师", # 角色
goal="分析数据并提供洞察", # 目标
backstory="你是一位资深分析师...", # 背景故事
verbose=True, # 详细输出
allow_delegation=True, # 是否可以委派任务
tools=[], # 可用工具
llm=..., # 使用的大模型
)

关键参数

  • role:角色名称,定义 Agent 的身份
  • goal:目标,定义 Agent 想要达成什么
  • backstory:背景故事,决定 Agent 的性格和行为方式
  • tools:Agent 可以使用的工具列表
  • llm:Agent 使用的大模型

2.2 Task(任务)

Task 定义 Agent 需要完成的具体工作。

1
2
3
4
5
6
7
8
from crewai import Task

task = Task(
description="分析销售数据,找出增长趋势",
expected_output="包含 5 个关键发现的报告",
agent=agent, # 执行任务的 Agent
output_file="report.md", # 输出文件
)

2.3 Crew(团队)

Crew 是 Agent 的集合,定义它们如何协作。

1
2
3
4
5
6
7
8
from crewai import Crew, Process

crew = Crew(
agents=[agent1, agent2, agent3],
tasks=[task1, task2, task3],
process=Process.sequential, # 或 Process.hierarchical
verbose=True,
)

协作模式

模式 说明 适用场景
Process.sequential 顺序执行,一个任务完成后执行下一个 流程明确的任务
Process.hierarchical 层级模式,自动分配 Manager Agent 协调 需要动态决策的任务

2.4 Tools(工具)

Tools 扩展 Agent 的能力,让它可以搜索、读写文件、调用 API 等。

1
2
3
4
5
6
7
8
9
10
from crewai_tools import SerperDevTool, FileReadTool

search_tool = SerperDevTool() # 搜索工具
file_tool = FileReadTool() # 文件读取工具

agent = Agent(
role="研究员",
tools=[search_tool, file_tool],
...
)

2.5 整体工作流程

1
2
3
4
5
6
7
8
9
10
11
12
13
┌─────────────────────────────────────────────────────────────┐
│ Crew │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Agent 1 │ │ Agent 2 │ │ Agent 3 │ │
│ │ (分析师) │ │ (研究员) │ │ (撰稿人) │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Task 1 │ │ Task 2 │ │ Task 3 │ │
│ │ 分析数据 │→│ 研究背景 │→│ 撰写报告 │ │
│ └─────────┘ └─────────┘ └─────────┘ │
└─────────────────────────────────────────────────────────────┘

三、安装与环境配置

3.1 环境要求

  • Python 3.10 - 3.13
  • 推荐使用 uv 作为包管理器

3.2 安装 CrewAI

方式一:使用 pip

1
2
3
4
5
# 基础安装
pip install crewai

# 安装额外工具
pip install 'crewai[tools]'

方式二:使用 uv(推荐)

1
2
3
4
5
6
# 安装 uv
pip install uv

# 安装 CrewAI
uv pip install crewai
uv pip install 'crewai[tools]'

3.3 创建项目

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 创建新项目
crewai create crew my_project

# 项目结构
my_project/
├── .env # 环境变量
├── pyproject.toml # 项目配置
└── src/my_project/
├── main.py # 入口文件
├── crew.py # Crew 定义
├── tools/ # 自定义工具
└── config/
├── agents.yaml # Agent 配置
└── tasks.yaml # Task 配置

3.4 常见安装问题

问题 1:ModuleNotFoundError: tiktoken

1
uv pip install 'crewai[embeddings]'

问题 2:Windows 上 Rust 编译错误

1
2
3
# 安装 Visual C++ Build Tools
# 或使用预编译包
uv pip install tiktoken --prefer-binary

四、大模型服务接入(重点)

这是大多数新手卡住的地方。CrewAI 默认使用 OpenAI,但你必须配置正确的 base_url 才能连接到你的大模型服务。

4.1 核心概念

为什么需要 base_url?

1
2
3
4
┌─────────────┐         ┌─────────────────────┐
│ CrewAI │ ────→ │ LLM 服务端点 │
│ (你的代码) │ HTTP │ (base_url) │
└─────────────┘ └─────────────────────┘
  • 默认情况下,CrewAI 会连接 https://api.openai.com/v1
  • 如果你用的是其他服务(阿里百炼、DeepSeek 等),必须指定 base_url
  • 否则会报错:Connection refusedInvalid API key

4.2 OpenAI 官方

1
2
3
4
5
6
7
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
model="gpt-4o",
api_key="sk-xxxxx",
# base_url 默认是 https://api.openai.com/v1,可以不填
)

环境变量方式

1
OPENAI_API_KEY=sk-xxxxx

4.3 Anthropic Claude

1
2
3
4
5
6
from langchain_anthropic import ChatAnthropic

llm = ChatAnthropic(
model="claude-sonnet-4-6",
api_key="sk-ant-xxxxx",
)

环境变量方式

1
ANTHROPIC_API_KEY=sk-ant-xxxxx

4.4 阿里百炼 Coding Plan(推荐)

阿里百炼 Coding Plan 提供两种兼容协议:

协议 Base URL 说明
OpenAI 兼容 https://coding.dashscope.aliyuncs.com/v1 使用 langchain-openai
Anthropic 兼容 https://coding.dashscope.aliyuncs.com/apps/anthropic 使用 langchain-anthropic

使用 OpenAI 兼容协议

1
2
3
4
5
6
7
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
model="qwen-max", # 通义千问模型
api_key="your_dashscope_key",
base_url="https://coding.dashscope.aliyuncs.com/v1", # 关键!
)

使用 Anthropic 兼容协议

1
2
3
4
5
6
7
from langchain_anthropic import ChatAnthropic

llm = ChatAnthropic(
model="qwen-max",
api_key="your_dashscope_key",
base_url="https://coding.dashscope.aliyuncs.com/apps/anthropic", # 关键!
)

环境变量方式

1
2
DASHSCOPE_API_KEY=your_dashscope_key
DASHSCOPE_BASE_URL=https://coding.dashscope.aliyuncs.com/v1

4.5 DeepSeek

1
2
3
4
5
6
7
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
model="deepseek-chat",
api_key="your_deepseek_key",
base_url="https://api.deepseek.com/v1", # 关键!
)

4.6 智谱 AI (GLM)

1
2
3
4
5
6
7
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
model="glm-4",
api_key="your_zhipu_key",
base_url="https://open.bigmodel.cn/api/paas/v4/", # 关键!
)

4.7 本地模型 (Ollama)

1
2
3
4
5
6
7
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
model="llama3",
api_key="ollama", # 任意值
base_url="http://localhost:11434/v1", # Ollama 默认端口
)

4.8 统一配置方案

在实际项目中,推荐使用配置文件统一管理:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# config/llm_config.py

import os
from langchain_openai import ChatOpenAI

def get_llm(provider: str = "dashscope"):
"""统一获取 LLM"""

configs = {
"openai": {
"model": "gpt-4o",
"api_key": os.getenv("OPENAI_API_KEY"),
"base_url": None,
},
"dashscope": {
"model": "qwen-max",
"api_key": os.getenv("DASHSCOPE_API_KEY"),
"base_url": "https://coding.dashscope.aliyuncs.com/v1",
},
"deepseek": {
"model": "deepseek-chat",
"api_key": os.getenv("DEEPSEEK_API_KEY"),
"base_url": "https://api.deepseek.com/v1",
},
}

config = configs.get(provider)
if not config or not config["api_key"]:
raise ValueError(f"请配置 {provider} 的 API Key")

return ChatOpenAI(
model=config["model"],
api_key=config["api_key"],
base_url=config["base_url"],
)

使用

1
2
3
4
5
# 默认使用阿里百炼
llm = get_llm()

# 切换到 OpenAI
llm = get_llm("openai")

4.9 Agent 中使用 LLM

1
2
3
4
5
6
7
8
9
from crewai import Agent
from config.llm_config import get_llm

agent = Agent(
role="分析师",
goal="分析数据",
backstory="你是一位资深分析师",
llm=get_llm("dashscope"), # 指定 LLM
)

五、项目结构详解

5.1 使用 CLI 创建项目

1
2
crewai create crew my_crew
cd my_crew

5.2 目录结构说明

1
2
3
4
5
6
7
8
9
10
11
12
13
14
my_crew/
├── .env # 环境变量(API Key 等)
├── pyproject.toml # Python 项目配置
├── README.md
└── src/my_crew/
├── __init__.py
├── main.py # 入口文件,运行 crew
├── crew.py # 定义 Crew、Agent、Task
├── tools/ # 自定义工具
│ ├── __init__.py
│ └── custom_tool.py
└── config/
├── agents.yaml # Agent 配置(角色、目标、背景)
└── tasks.yaml # Task 配置(描述、预期输出)

5.3 agents.yaml 配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# config/agents.yaml

researcher:
role: >
{topic} 高级研究员
goal: >
深入研究 {topic} 领域的最新发展
backstory: >
你是一位经验丰富的研究员,擅长发现最前沿的技术趋势。
你以能够找到最相关信息并以清晰简洁的方式呈现而闻名。

analyst:
role: >
{topic} 数据分析师
goal: >
分析研究数据并生成洞察报告
backstory: >
你是一位严谨的分析师,擅长将复杂数据转化为可执行的洞察。

占位符说明

  • {topic} 会在运行时被替换为实际值

5.4 tasks.yaml 配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# config/tasks.yaml

research_task:
description: >
{topic} 进行全面研究,找出最新、最相关的信息。
expected_output: >
包含 10 个关键发现的要点列表
agent: researcher # 执行此任务的 Agent

analysis_task:
description: >
分析研究结果,生成详细的分析报告。
expected_output: >
一份完整的 Markdown 格式报告
agent: analyst
output_file: report.md # 输出文件

5.5 crew.py 定义

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
# crew.py

from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task

@CrewBase
class MyCrew():
"""我的 Crew"""

@agent
def researcher(self) -> Agent:
return Agent(
config=self.agents_config['researcher'],
verbose=True,
)

@agent
def analyst(self) -> Agent:
return Agent(
config=self.agents_config['analyst'],
verbose=True,
)

@task
def research_task(self) -> Task:
return Task(
config=self.tasks_config['research_task'],
)

@task
def analysis_task(self) -> Task:
return Task(
config=self.tasks_config['analysis_task'],
output_file='report.md',
)

@crew
def crew(self) -> Crew:
return Crew(
agents=self.agents,
tasks=self.tasks,
process=Process.sequential,
verbose=True,
)

5.6 main.py 入口

1
2
3
4
5
6
7
8
9
10
11
12
13
# main.py

from my_crew.crew import MyCrew

def run():
"""运行 Crew"""
inputs = {
'topic': 'AI Agents'
}
MyCrew().crew().kickoff(inputs=inputs)

if __name__ == "__main__":
run()

5.7 运行项目

1
2
3
4
5
# 方式一:使用 CLI
crewai run

# 方式二:直接运行 Python
python src/my_crew/main.py

六、实战:构建一人公司 Agent 团队

6.1 场景描述

假设你要开发一个「人生规划器」App,但你只有一个人。你可以创建一个 Agent 团队来帮你:

  • CEO Agent:负责决策和协调
  • CTO Agent:负责技术架构
  • 产品经理 Agent:负责需求分析
  • 工程师 Agent:负责代码实现
  • 测试 Agent:负责质量保证

6.2 项目结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
life-planner-crew/
├── .env
├── requirements.txt
├── main.py
├── agents/
│ ├── ceo_agent.py
│ ├── cto_agent.py
│ ├── product_manager.py
│ ├── backend_engineer.py
│ ├── frontend_engineer.py
│ └── qa_agent.py
├── tasks/
│ ├── requirement_tasks.py
│ ├── development_tasks.py
│ └── test_tasks.py
├── crews/
│ └── development_crew.py
├── tools/
│ └── file_tools.py
└── config/
├── project_config.py
└── llm_config.py

6.3 LLM 配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# config/llm_config.py

import os
from langchain_openai import ChatOpenAI

DASHSCOPE_API_KEY = os.getenv("DASHSCOPE_API_KEY")
DASHSCOPE_BASE_URL = "https://coding.dashscope.aliyuncs.com/v1"

def get_default_llm():
"""默认模型(用于决策类 Agent)"""
return ChatOpenAI(
model="qwen-max",
api_key=DASHSCOPE_API_KEY,
base_url=DASHSCOPE_BASE_URL,
)

def get_efficient_llm():
"""高效模型(用于执行类 Agent)"""
return ChatOpenAI(
model="qwen-turbo",
api_key=DASHSCOPE_API_KEY,
base_url=DASHSCOPE_BASE_URL,
)

6.4 Agent 定义

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# agents/ceo_agent.py

from crewai import Agent
from config.llm_config import get_default_llm

def create_ceo_agent():
return Agent(
role="CEO - 公司首席执行官",
goal="""
负责:
1. 战略决策和目标设定
2. 团队协调和资源分配
3. 处理 Agent 团队分歧
4. 确保项目按时保质完成
""",
backstory="""
你是一位经验丰富的技术创业者。
决策果断但善于倾听,关注商业价值。
""",
verbose=True,
allow_delegation=True, # 可以委派任务
llm=get_default_llm(),
)

# agents/backend_engineer.py

def create_backend_engineer_agent():
return Agent(
role="后端工程师",
goal="实现 API 和数据库逻辑",
backstory="你专注于 Node.js 后端开发",
verbose=True,
allow_delegation=False,
llm=get_efficient_llm(), # 使用高效模型
)

6.5 Crew 配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# crews/development_crew.py

from crewai import Crew, Process
from agents import (
create_ceo_agent,
create_cto_agent,
create_product_manager,
create_backend_engineer,
)

def create_development_crew():
# 创建 Agent
ceo = create_ceo_agent()
cto = create_cto_agent()
pm = create_product_manager()
backend = create_backend_engineer()

return Crew(
agents=[ceo, cto, pm, backend],
tasks=[], # 动态添加
process=Process.hierarchical, # 层级模式
manager_llm="qwen-max",
manager_agent=ceo, # CEO 作为管理者
verbose=True,
)

6.6 运行效果

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
python main.py

# 输出
╔═══════════════════════════════════════════════════════════════╗
║ 🎭 Life Planner Crew - 一人公司 Agent 团队 🎭 ║
╚═══════════════════════════════════════════════════════════════╝

📋 检查环境配置...
✓ DASHSCOPE_API_KEY 已配置
✓ 项目目录存在

🎯 请选择操作模式:
[1] 初始化项目
[2] 功能开发模式
[3] 决策讨论模式

七、常见问题与解决方案

Q1: 连接大模型失败

错误信息

1
ConnectionError: Failed to connect to api.openai.com

原因:没有配置正确的 base_url

解决

1
2
3
4
5
6
7
8
9
# 错误 ❌
llm = ChatOpenAI(model="qwen-max", api_key="xxx")

# 正确 ✅
llm = ChatOpenAI(
model="qwen-max",
api_key="xxx",
base_url="https://coding.dashscope.aliyuncs.com/v1",
)

Q2: API Key 格式错误

错误信息

1
AuthenticationError: Invalid API key

检查项

  1. API Key 是否正确复制(没有多余空格)
  2. 是否填对了环境变量名
  3. .env 文件是否被正确加载

解决

1
2
3
4
5
6
7
# 确保加载 .env
from dotenv import load_dotenv
load_dotenv()

# 验证 API Key
import os
print(os.getenv("DASHSCOPE_API_KEY"))

Q3: Agent 输出不符合预期

原因:角色定义不够清晰

解决:优化 backstory

1
2
3
4
5
6
7
8
9
10
11
# 不好 ❌
backstory="你是一个程序员"

# 更好 ✅
backstory="""
你是一位专注 Node.js 后端开发的工程师。
- 擅长 RESTful API 设计
- 遵循 Clean Code 原则
- 注重代码可维护性
- 使用 TypeScript 和 NestJS
"""

Q4: 依赖安装失败

Windows 上常见问题

1
2
3
4
# 安装 Visual C++ Build Tools
# 或使用预编译包
pip install tiktoken --prefer-binary
pip install 'crewai[embeddings]'

Q5: 如何调试 Agent

开启 verbose 模式

1
2
3
4
5
6
7
8
9
agent = Agent(
role="分析师",
verbose=True, # 输出详细过程
)

crew = Crew(
agents=[agent],
verbose=True, # 输出团队协作过程
)

八、总结

核心要点

  1. CrewAI 是什么:多 Agent 协作框架,让多个 AI 角色协同完成任务
  2. 核心概念:Agent(角色)、Task(任务)、Crew(团队)、Tools(工具)
  3. 关键配置:LLM 接入必须配置 base_url,这是大多数人踩坑的地方

大模型接入速查表

服务商 base_url 备注
OpenAI 默认 无需配置
阿里百炼 Coding Plan https://coding.dashscope.aliyuncs.com/v1 OpenAI 兼容
DeepSeek https://api.deepseek.com/v1 OpenAI 兼容
智谱 AI https://open.bigmodel.cn/api/paas/v4/ OpenAI 兼容
Ollama http://localhost:11434/v1 本地模型

学习资源

下一步

  1. 尝试创建你的第一个 Crew
  2. 接入你喜欢的大模型服务
  3. 设计适合你场景的 Agent 角色
  4. 组合 Crews 和 Flows 构建复杂工作流

作者:AI 技术探索者
日期:2026-03-31

本文基于 CrewAI v1.12+ 和阿里百炼 Coding Plan 服务编写

背景

2023 年 ChatGPT 火了,2024 年 Agent 热了,2025 年 AI 应用全面开花。Java 开发者的 AI 工具箱已经非常成熟——Spring AI 1.0 GA 在 2025 年 5 月正式发布,经过近一年的迭代,已经成为企业级 Java AI 应用的事实标准。

这篇文章站在当下时间点,从产生背景架构演进,从与 LangChain4J 的深度对比实战代码,让你看完就能上手做 AI 应用。不讲虚的,全是干货。


一、Spring AI 是什么,为什么需要它

1. Java 开发者的 AI 困境(2023-2024)

AI 大模型爆发初期,Java 开发者面临两难选择:

方案 问题
直接调用 API 每个服务商 API 不同,切换成本高;缺乏高级抽象(RAG、对话记忆、Agent 等)
用 Python 框架 LangChain、LlamaIndex 都是 Python 原生,Java 项目得跨语言集成,架构不统一

更关键的是:企业级 Java 应用 80% 以上跑在 Spring 上,需要一个原生融入 Spring 生态的 AI 框架。

2. Spring AI 的诞生与演进

Spring AI 的版本演进时间线:

时间节点 版本 里程碑意义
2023 年 11 月 0.8.0 项目启动,首个 Milestone
2024 年全年 0.8.x - 0.9.x 快速迭代,积累社区反馈
2025 年 5 月 1.0.0 GA Spring I/O 2025 正式发布,生产就绪
2025 年下半年 1.0.x - 1.1.x 稳定迭代,修复问题,增加 MCP 支持
2026 年初 1.1.x / 1.2 Agent 能力增强,国产模型支持完善

1.0 GA 版本的核心里程碑

  • API 稳定:ChatClient、Advisor、VectorStore 等核心接口不再变化
  • 生产就绪:Observability、错误处理、配置管理达到企业级标准
  • 生态完善:官方支持 20+ 模型服务商,10+ 向量数据库
  • 文档成熟:官方文档完善,示例丰富,社区活跃

3. 当前定位

站在今天,Spring AI 已经是:

Java 企业级 AI 应用的标准框架,Spring 生态的 AI 基础设施。

一句话概括:Spring AI 是 Java 界的 LangChain,但它比 LangChain 更懂企业级应用。

4. 核心价值矩阵

价值点 说明 企业收益
统一 API 抽象 OpenAI、Azure、Anthropic、Ollama、国产模型……一个接口搞定 模型切换零代码改动,供应商议价能力提升
Spring 原生集成 自动配置、依赖注入、Observability、配置中心 Spring 开发者零学习成本,复用现有基础设施
企业级特性 Token 消耗监控、调用链追踪、熔断降级、安全审计 生产环境直接部署,运维体系一体化
高级 AI 抽象 RAG、Agent、MCP、Function Calling、对话记忆 不用自己造轮子,专注业务逻辑
国产模型支持 阿里通义、百度文心、讯飞星火、腾讯混元 数据合规、成本可控、中文效果优化

二、架构设计:三层抽象 + MCP 协议层

Spring AI 1.0 的架构已经稳定,可以概括为四层:

1
2
3
4
5
6
7
8
9
10
11
12
13
┌─────────────────────────────────────────────────────────────┐
│ 应用层 (Application) │
│ ChatClient / PromptTemplate / Advisor / Agent │
├─────────────────────────────────────────────────────────────┤
│ MCP 协议层 (Protocol) │
│ MCP Client / MCP Server / Tool Registry │
├─────────────────────────────────────────────────────────────┤
│ 核心抽象层 (Core Abstractions) │
│ ChatModel / EmbeddingModel / ImageModel / AudioModel │
├─────────────────────────────────────────────────────────────┤
│ 集成层 (Integrations) │
│ OpenAI / Azure / Anthropic / Ollama / Alibaba / VectorDB │
└─────────────────────────────────────────────────────────────┘

1. 核心抽象层:统一接口设计

Spring AI 定义了一套稳定的模型接口,不管底层用哪个服务商,API 都一样。

ChatModel——对话模型

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// 核心接口定义(1.0 GA 后已稳定)
public interface ChatModel extends Model<Prompt, ChatResponse> {
ChatResponse call(Prompt prompt);
}

// 使用示例:服务商切换只需改配置,代码不动
@Autowired
private ChatModel chatModel; // 配置决定具体实现(OpenAI、Azure、Ollama...)

public String chat(String userMessage) {
Prompt prompt = new Prompt(userMessage);
ChatResponse response = chatModel.call(prompt);
return response.getResult().getOutput().getContent();
}

EmbeddingModel——向量嵌入模型

1
2
3
4
5
6
7
8
9
10
11
12
13
14
public interface EmbeddingModel extends Model<EmbeddingRequest, EmbeddingResponse> {
EmbeddingResponse embed(EmbeddingRequest request);

// 1.0 新增:批量嵌入
List<float[]> embed(List<String> texts);
}

// 使用示例
@Autowired
private EmbeddingModel embeddingModel;

public float[] embed(String text) {
return embeddingModel.embed(text);
}

ImageModel——图像生成模型

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
public interface ImageModel extends Model<ImagePrompt, ImageResponse> {
ImageResponse call(ImagePrompt prompt);
}

// 支持 DALL-E 3、Stability AI、Midjourney API
@Autowired
private ImageModel imageModel;

public String generateImage(String promptText) {
ImagePrompt prompt = new ImagePrompt(promptText,
ImageOptions.builder()
.width(1024)
.height(1024)
.style("vivid")
.build());
return imageModel.call(prompt).getResult().getOutput().getUrl();
}

2. 应用层:高级功能封装

ChatClient——对话客户端(1.0 推荐使用)

ChatClient 是 Spring AI 1.0 推荐的高级 API,采用流式 Builder 模式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
@Autowired
private ChatClient.Builder chatClientBuilder;

// 构建带默认配置的 ChatClient
ChatClient chatClient = chatClientBuilder
.defaultSystem("你是一个专业的 Java 开发顾问")
.defaultOptions(ChatOptions.builder()
.model("gpt-4o")
.temperature(0.7)
.build())
.build();

// 简单调用
String response = chatClient.prompt()
.user("解释一下 Spring 的依赖注入")
.call()
.content();

// 流式响应(SSE 或 WebSocket)
chatClient.prompt()
.user("写一个 Spring Boot 启动流程分析")
.stream()
.content()
.subscribe(chunk -> System.out.print(chunk));

// 结构化输出(1.0 新增)
Person person = chatClient.prompt()
.user("从文本中提取人物信息:张三,35岁,北京人")
.call()
.entity(Person.class); // 自动转换为 POJO

PromptTemplate——提示词模板

支持 Mustache 语法,动态生成提示词:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
PromptTemplate template = new PromptTemplate("""
请根据以下信息回答问题:

用户姓名:{{name}}
用户角色:{{role}}
问题:{{question}}

请以{{style}}的风格回答。
""");

Map<String, Object> params = Map.of(
"name", "张三",
"role", "架构师",
"question", "如何设计微服务架构",
"style", "专业简洁"
);

Prompt prompt = template.create(params);

Advisor——拦截器模式(1.0 正式 API)

Advisor 是 Spring AI 1.0 的核心拦截器机制,有两种类型:

  • CallAroundAdvisor:同步调用拦截
  • StreamAroundAdvisor:流式调用拦截
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
// 自定义 Advisor(1.0 正式 API)
public class LoggingAdvisor implements CallAroundAdvisor {

@Override
public String getName() {
return "LoggingAdvisor";
}

@Override
public int getOrder() {
return 0; // 执行顺序
}

@Override
public AdvisedResponse aroundCall(AdvisedRequest request, CallAroundAdvisorChain chain) {
// 前置处理:记录请求
log.info("AI Request: {}", request.userText());

// 执行调用
AdvisedResponse response = chain.nextAroundCall(request);

// 后置处理:记录响应
log.info("AI Response: {}", response.response().getResult().getOutput().getContent());

return response;
}
}

// 内置 Advisor:QuestionAnswerAdvisor(RAG 自动检索)
QuestionAnswerAdvisor qaAdvisor = new QuestionAnswerAdvisor(
vectorStore,
SearchRequest.defaults()
);

// 内置 Advisor:对话记忆
PromptChatMemoryAdvisor memoryAdvisor = new PromptChatMemoryAdvisor(
chatMemory,
"conversation-123"
);

// 使用多个 Advisor(链式执行)
String response = chatClient.prompt()
.user("什么是 Spring AI?")
.advisors(memoryAdvisor, qaAdvisor, loggingAdvisor)
.call()
.content();

Agent——自主任务执行(1.1+ 新增)

Spring AI 1.1 开始引入 Agent 抽象,支持自主任务分解和执行:

1
2
3
4
5
6
7
8
9
10
// Agent 基础示例
@Autowired
private Agent agent;

public String executeTask(String task) {
return agent.execute(task)
.plan() // 自主规划
.execute() // 执行步骤
.result(); // 返回结果
}

3. MCP 协议层:AI 的 USB-C 接口

MCP(Model Context Protocol) 是 Anthropic 在 2024 年推出的开放协议,2025 年成为 AI 工具连接的事实标准。Spring AI 1.0 正式支持 MCP。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
MCP 架构:
┌─────────────────────────────────────────────────────────────┐
│ Spring AI MCP Layer │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌──────────────┐ │
│ │ MCP Client │──────► MCP Servers │ │
│ │ (Spring AI) │ │ (Tool/DB/API)│ │
│ └─────────────┘ └──────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────┐ ┌──────────────┐ │
│ │ ChatClient │ │ GitHub MCP │ │
│ │ Agent │ │ File MCP │ │
│ │ │ │ Postgres MCP │ │
│ └─────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘

使用 MCP Server

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// 配置 MCP Server
spring.ai.mcp.servers.github.type=stdio
spring.ai.mcp.servers.github.command=/usr/local/bin/github-mcp-server

// 使用 MCP 工具
ChatClient client = ChatClient.builder(chatModel)
.defaultMcpServers("github", "filesystem", "postgres")
.build();

String response = client.prompt()
.user("查看我最近的 GitHub PR,并总结变更内容")
.call()
.content();
// Agent 会自动调用 GitHub MCP Server 获取 PR 数据

4. 集成层:服务商适配现状(2026)

类型 支持的服务商 状态
对话模型 OpenAI、Azure OpenAI、Anthropic Claude、Google Gemini、Amazon Bedrock、阿里通义、百度文心、讯飞星火、腾讯混元、Ollama ✅ 生产就绪
Embedding OpenAI、Azure、阿里通义、本地模型 ✅ 生产就绪
图像生成 OpenAI DALL-E 3、Stability AI、Azure ✅ 生产就绪
向量数据库 Pinecone、Chroma、Weaviate、Milvus、Redis、PostgreSQL/pgvector、MongoDB、Elasticsearch ✅ 生产就绪
MCP Server GitHub、Filesystem、PostgreSQL、Slack、Google Drive(官方),第三方生态丰富 ✅ 1.0+ 支持

三、Spring 生态兼容方案

Spring AI 最大的优势是原生融入 Spring 生态,这是 LangChain4J 无法比拟的。

1. 自动配置(Spring Boot Starter)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<!-- OpenAI -->
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-openai-spring-boot-starter</artifactId>
<version>1.1.0</version>
</dependency>

<!-- 阿里云通义千问 -->
<dependency>
<groupId>com.alibaba.cloud.ai</groupId>
<artifactId>spring-ai-alibaba-starter</artifactId>
<version>1.0.0</version>
</dependency>

<!-- 向量数据库 -->
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-milvus-store-spring-boot-starter</artifactId>
</dependency>

2. Observability(可观测性)

Spring AI 自动集成 Spring Boot Actuator,AI 调用的可观测性零配置开启

1
2
3
4
5
6
7
8
9
10
management:
endpoints:
web:
exposure:
include: health,metrics,prometheus
tracing:
enabled: true
observations:
ai:
enabled: true # AI 调用自动追踪

自动上报的指标

指标 说明
ai.chat.tokens.used Token 消耗量(Prompt + Completion)
ai.chat.latency 调用耗时(P50、P95、P99)
ai.chat.success.rate 成功率
ai.embedding.latency Embedding 耗时
ai.vectorstore.search.latency 向量检索耗时

自动追踪的 Span

1
2
3
4
5
6
AI Chat Call
├── ai-chat-request (Prompt 构建)
├── ai-chat-model-call (LLM 调用)
│ ├── token-count (Token 计算)
│ └── response-parse (响应解析)
└── ai-chat-response (结果处理)

3. Spring Cloud 集成

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
// 配置中心:模型参数动态刷新
@RefreshScope
@Service
public class AiService {

@Value("${spring.ai.openai.chat.options.model}")
private String model;

@Value("${spring.ai.openai.chat.options.temperature}")
private Double temperature;
}

// 熔断降级:AI 调用失败保护
@Service
public class ResilientAiService {

@Autowired
private ChatClient chatClient;

@CircuitBreaker(name = "aiService", fallbackMethod = "fallback")
@Retry(name = "aiService")
@RateLimiter(name = "aiService")
public String chat(String message) {
return chatClient.prompt()
.user(message)
.call()
.content();
}

public String fallback(String message, Exception e) {
return "AI 服务暂时不可用,请稍后重试";
}
}

4. Spring Security 集成

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// AI API Key 安全管理
@Configuration
public class AiSecurityConfig {

@Bean
public ChatModel chatModel(KeyProvider keyProvider) {
// Key 从 Vault 或密钥管理服务获取
String apiKey = keyProvider.getApiKey("openai");

return OpenAiChatModel.builder()
.apiKey(apiKey)
.build();
}
}

// 用户级 AI 权限控制
@Service
public class SecuredAiService {

@PreAuthorize("hasRole('AI_USER')")
public String chat(String message) {
// 只有 AI_USER 角色才能调用
return chatClient.prompt().user(message).call().content();
}
}

四、Spring AI vs LangChain4J:2026 年深度对比

LangChain4J 是另一个流行的 Java AI 框架,两者经常被拿来对比。站在 2026 年的视角,对比结果已经清晰。

1. 版本成熟度对比

框架 最新版本 发布时间 成熟度
Spring AI 1.1.x / 1.2 2025.05 GA 生产就绪,API 稳定
LangChain4J 1.0.x 2025.06 GA 生产就绪,社区活跃

两者都在 2025 年上半年发布了 1.0 GA 版本,生产就绪度相当。

2. 设计哲学对比

维度 Spring AI LangChain4J
设计哲学 Spring 原生,企业级优先 轻量独立,框架中立
依赖要求 必须有 Spring Boot 3.x 无强制依赖,支持 Quarkus/Micronaut/Spring
API 风格 Builder 模式 + Advisor 链 流式 API + AI Services 注解
配置方式 YAML 自动配置 + Actuator 代码 Builder 配置
生态集成 Spring 全生态无缝集成 需手动集成各框架

3. 核心能力对比

能力 Spring AI LangChain4J 说明
Chat ✅ ChatClient ✅ ChatLanguageModel 都成熟
Embedding ✅ EmbeddingModel ✅ EmbeddingModel 都成熟
RAG ✅ QuestionAnswerAdvisor ✅ ContentRetriever + Augmentor Spring AI 更简洁
Function Calling ✅ @Bean + @Description ✅ @Tool 注解 LangChain4J 更直观
对话记忆 ✅ PromptChatMemoryAdvisor ✅ ChatMemoryProvider 都成熟
结构化输出 ✅ .entity(Class) ✅ 返回 POJO 都成熟
MCP 协议 ✅ 1.0+ 原生支持 ✅ 1.0+ 支持 Spring AI 集成更深
Agent ⚠️ 1.1+ 基础支持 ✅ 成熟的 Agent 框架 LangChain4J 更成熟
Observability ✅ Actuator 自动集成 ⚠️ 需手动配置 Spring AI 完胜
国产模型 ✅ 官方支持阿里/百度/讯飞 ⚠️ 需自行适配 Spring AI 优势

4. 代码风格对比

对话模型

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// Spring AI:流式 Builder
@Autowired
private ChatClient chatClient;

String response = chatClient.prompt()
.system("你是一个专业的顾问")
.user("你好")
.advisors(memoryAdvisor)
.call()
.content();

// LangChain4J:直接调用
ChatLanguageModel model = OpenAiChatModel.builder()
.apiKey("key")
.modelName("gpt-4o")
.build();

String response = model.generate("你好");

AI Services 注解(LangChain4J 特色)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// LangChain4J 的声明式 AI Services
interface Assistant {
@SystemMessage("你是一个专业的 Java 顾问,回答要简洁")
String chat(@UserMessage String question);

@UserMessage("讲一个关于 {{topic}} 的笑话")
String tellJoke(@V("topic") String topic);
}

// 一行代码构建
Assistant assistant = AiServices.builder(Assistant.class)
.chatLanguageModel(model)
.chatMemoryProvider(id -> MessageWindowChatMemory.withMaxMessages(10))
.tools(new MyTools())
.build();

// Spring AI 需要用 ChatClient + PromptTemplate 实现
// 目前没有直接的 AI Services 对应

RAG 实现

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
// Spring AI:Advisor 自动处理
@Autowired
private VectorStore vectorStore;

QuestionAnswerAdvisor qaAdvisor = new QuestionAnswerAdvisor(
vectorStore,
SearchRequest.defaults().withTopK(5)
);

String response = chatClient.prompt()
.user("什么是 Spring AI?")
.advisors(qaAdvisor)
.call()
.content();

// LangChain4J:ContentRetriever + Augmentor
ContentRetriever retriever = EmbeddingStoreContentRetriever.builder()
.embeddingStore(embeddingStore)
.embeddingModel(embeddingModel)
.maxResults(5)
.build();

Augmentor augmentor = DefaultAugmentor.builder()
.contentRetriever(retriever)
.build();

Assistant assistant = AiServices.builder(Assistant.class)
.chatLanguageModel(model)
.augmentor(augmentor)
.build();

5. Agent 能力对比(关键差异)

LangChain4J 的 Agent 更成熟

1
2
3
4
5
6
7
8
9
10
// LangChain4J:完整的 Agent 框架
Agent agent = Agent.builder()
.chatLanguageModel(model)
.tools(new FileTools(), new WebSearchTools(), new DatabaseTools())
.chatMemoryProvider(id -> MessageWindowChatMemory.withMaxMessages(20))
.systemMessage("你是一个自主解决问题的助手...")
.build();

// Agent 自主执行复杂任务
String result = agent.run("分析这份文档,找出关键问题,并生成改进建议");

Spring AI 的 Agent(1.1+)还在发展

1
2
3
4
5
6
7
// Spring AI:基础 Agent 能力
AgentExecutor executor = AgentExecutor.builder()
.chatModel(chatModel)
.tools(toolRegistry)
.build();

AgentResult result = executor.execute("任务描述");

结论:复杂 Agent 应用,LangChain4J 目前更成熟;企业级可观测 Agent,Spring AI 更适合。

6. 选型决策矩阵

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
选型决策树:

├─ 项目技术栈?
│ ├─ Spring Boot → Spring AI(生态融合度最高,必选)
│ ├─ Quarkus → LangChain4J(官方支持更好)
│ ├─ Micronaut → LangChain4J
│ └─ 纯 Java → LangChain4J(轻量)

├─ 是否需要企业级特性?
│ ├─ Observability 重要 → Spring AI(零配置集成)
│ ├─ Spring Cloud 配置中心 → Spring AI
│ ├─ Spring Security 权限 → Spring AI
│ └─ 不需要 → LangChain4J 或 Spring AI 都行

├─ Agent 复杂度?
│ ├─ 复杂自主 Agent → LangChain4J(Agent 框架更成熟)
│ ├─ 简单对话 + RAG → Spring AI(QuestionAnswerAdvisor 更简洁)
│ └─ 可观测 Agent → Spring AI

├─ 国产模型需求?
│ ├─ 阿里通义/百度文心 → Spring AI(官方支持)
│ └─ 国际模型为主 → 两者都支持

├─ 团队熟悉度?
│ ├─ Spring 开发者 → Spring AI(零学习成本)
│ ├─ 非 Spring 开发者 → LangChain4J

└─ 快速原型?
├─ 声明式接口 → LangChain4J AI Services(接口定义即实现)
└─ Spring 体系 → Spring AI ChatClient

一句话总结

场景 推荐
Spring Boot 企业项目 Spring AI(必选)
Quarkus/Micronaut 项目 LangChain4J
复杂自主 Agent LangChain4J(Agent 更成熟)
RAG + 可观测性 Spring AI(Advisor + Actuator)
国产模型合规 Spring AI(官方支持)
快速原型 LangChain4J AI Services

五、实战:Spring AI 经典实践

1. 基础对话应用

Maven 依赖(Spring Boot 3.x)

1
2
3
4
5
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-openai-spring-boot-starter</artifactId>
<version>1.1.0</version>
</dependency>

配置

1
2
3
4
5
6
7
8
9
spring:
ai:
openai:
api-key: ${OPENAI_API_KEY}
base-url: https://api.openai.com # 可切换代理地址
chat:
options:
model: gpt-4o-mini
temperature: 0.7

Controller(推荐写法)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
@RestController
@RequestMapping("/api/chat")
public class ChatController {

private final ChatClient chatClient;

// 推荐:构造时注入,一次性构建
public ChatController(ChatClient.Builder builder) {
this.chatClient = builder
.defaultSystem("你是一个友好的助手,用简洁的语言回答")
.defaultOptions(ChatOptions.builder()
.temperature(0.7)
.build())
.build();
}

@PostMapping
public String chat(@RequestBody String message) {
return chatClient.prompt()
.user(message)
.call()
.content();
}

@GetMapping("/stream")
public Flux<String> streamChat(@RequestParam String message) {
return chatClient.prompt()
.user(message)
.stream()
.content();
}

// 结构化输出
@PostMapping("/extract")
public Summary extract(@RequestBody String text) {
return chatClient.prompt()
.user("总结以下文本:\n" + text)
.call()
.entity(Summary.class);
}
}

public record Summary(String title, List<String> keyPoints, String conclusion) {}

2. Function Calling(工具调用)

Spring AI 1.0 的 Function Calling 已经非常成熟:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
@Configuration
public class AiFunctions {

// 方式一:Spring Bean 函数
@Bean
@Description("查询指定城市的实时天气信息")
public Function<WeatherRequest, WeatherResponse> weatherFunction(WeatherService weatherService) {
return request -> weatherService.getCurrentWeather(request.city());
}

// 方式二:复杂函数
@Bean
@Description("在数据库中搜索相关文档")
public Function<SearchRequest, List<Document>> searchDocuments(DocumentRepository repo) {
return request -> repo.searchByKeyword(request.keyword(), request.limit());
}
}

public record WeatherRequest(String city) {}
public record WeatherResponse(String city, double temperature, String condition, int humidity) {}
public record SearchRequest(String keyword, int limit) {}

// Controller 使用
@RestController
public class WeatherController {

private final ChatClient chatClient;

public WeatherController(ChatClient.Builder builder) {
this.chatClient = builder
.defaultFunctions("weatherFunction", "searchDocuments")
.build();
}

@GetMapping("/weather")
public String askWeather(@RequestParam String question) {
// LLM 自动识别需要调用 weatherFunction
// 如 "北京今天天气怎么样?适合户外运动吗?"
return chatClient.prompt()
.user(question)
.call()
.content();
}
}

3. RAG 应用实战(QuestionAnswerAdvisor)

Spring AI 1.0 的 RAG 实现已经非常简洁:

1
2
3
4
5
6
7
8
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-pdf-document-reader</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-milvus-store-spring-boot-starter</artifactId>
</dependency>

文档导入服务

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
@Service
public class DocumentService {

private final EmbeddingModel embeddingModel;
private final VectorStore vectorStore;

public DocumentService(EmbeddingModel embeddingModel, VectorStore vectorStore) {
this.embeddingModel = embeddingModel;
this.vectorStore = vectorStore;
}

public void importPdf(String filePath) {
// 1. 读取 PDF
Resource resource = new FileSystemResource(filePath);
TikaDocumentReader reader = new TikaDocumentReader(resource);
List<Document> documents = reader.get();

// 2. 分块
TokenTextSplitter splitter = new TokenTextSplitter(
500, // 默认块大小
100, // 重叠大小
5, // 最小块大小
10000, // 最大块大小
true // 保持段落完整
);
List<Document> chunks = splitter.split(documents);

// 3. 向量化并存入 VectorStore(自动 Embedding)
vectorStore.add(chunks);
}
}

RAG 查询服务(使用 QuestionAnswerAdvisor)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
@Service
public class RagService {

private final ChatClient chatClient;
private final VectorStore vectorStore;

public RagService(ChatClient.Builder builder, VectorStore vectorStore) {
this.vectorStore = vectorStore;

// 核心:QuestionAnswerAdvisor 自动处理检索和上下文注入
QuestionAnswerAdvisor qaAdvisor = new QuestionAnswerAdvisor(
vectorStore,
SearchRequest.defaults()
.withTopK(5)
.withSimilarityThreshold(0.7)
);

this.chatClient = builder
.defaultSystem("""
你是一个专业的问答助手。
请严格基于提供的文档内容回答问题。
如果文档中没有相关信息,请明确告知"文档中未找到相关内容"。
回答时请标注信息来源。
""")
.defaultAdvisors(qaAdvisor)
.build();
}

public String query(String question) {
// Advisor 自动检索相关文档并注入上下文
return chatClient.prompt()
.user(question)
.call()
.content();
}
}

对比:Spring AI 的 RAG 只需要 3 行核心代码,LangChain4J 需要更多配置。

4. 使用阿里云通义千问(国产模型)

国内项目首选阿里云,性价比高,中文效果好:

1
2
3
4
5
<dependency>
<groupId>com.alibaba.cloud.ai</groupId>
<artifactId>spring-ai-alibaba-starter</artifactId>
<version>1.0.0</version>
</dependency>
1
2
3
4
5
6
7
spring:
ai:
alibaba:
api-key: ${DASHSCOPE_API_KEY}
chat:
options:
model: qwen-plus # qwen-turbo / qwen-plus / qwen-max
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
@Service
public class AlibabaAiService {

private final ChatClient chatClient;

public AlibabaAiService(ChatClient.Builder builder) {
this.chatClient = builder
.defaultSystem("你是一个专业的中文顾问")
.build();
}

public String chat(String message) {
return chatClient.prompt()
.user(message)
.call()
.content();
}
}

支持的通义模型:

  • qwen-turbo:速度快,成本低,适合简单对话
  • qwen-plus:能力均衡,推荐日常使用
  • qwen-max:最强推理,适合复杂任务
  • qwen-vl:多模态,支持图像理解

5. MCP 工具集成

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 配置 MCP Server
spring:
ai:
mcp:
servers:
github:
type: stdio
command: /usr/local/bin/github-mcp-server
args:
- --token=${GITHUB_TOKEN}
filesystem:
type: stdio
command: /usr/local/bin/fs-mcp-server
args:
- --root=/data/documents
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
@Service
public class McpAiService {

private final ChatClient chatClient;

public McpAiService(ChatClient.Builder builder) {
this.chatClient = builder
.defaultMcpServers("github", "filesystem")
.build();
}

public String analyzeGithubPr(String repo, int prNumber) {
return chatClient.prompt()
.user("分析 " + repo + " 的 PR #" + prNumber + " 的变更内容")
.call()
.content();
// 自动调用 GitHub MCP Server 获取 PR 数据
}
}

六、Spring AI 在 AI 潮流中的作用与影响

1. 降低 Java 企业接入 AI 的门槛

经过近一年的生产验证,Spring AI 已经证明了自己的价值:

2024 年痛点 2026 年现状
Java 开发者被迫学 Python Spring 开发者零学习成本接入 AI
跨语言架构复杂 单一技术栈,架构统一
缺乏企业级特性 Observability、安全、配置管理一体化

数据佐证:Spring AI GitHub Stars 从 2024 年的几千增长到 2026 年的数万,企业采用率快速增长。

2. 推动 AI 应用标准化

Spring AI 带来的标准化价值:

标准化 影响
API 统一 模型切换零成本,供应商议价能力提升
Prompt 模板化 版本管理、复用、测试规范化
RAG 模式 QuestionAnswerAdvisor 成为参考模式
Observability AI 调用监控追踪有 Spring 标准
MCP 协议 工具连接有开放标准,生态繁荣

3. 企业级 AI 应用的基础设施

Spring AI 不是玩具框架,是生产级基础设施:

能力 Spring AI 实现
可观测性 Actuator 自动集成,Token 消耗、耗时、成功率自动上报
可配置 YAML 配置 + 配置中心动态刷新
可扩展 新服务商扩展简单,遵循 Spring 模式
可集成 Spring Cloud、Security、Data 一体化
可运维 熔断、限流、重试、降级开箱即用

4. 与 LangChain 生态的分工协作

生态 定位 2026 状态
LangChain(Python) AI 创新的前沿试验场 继续引领新模式
LangChain4J Java 轻量级选择,Agent 优先 Agent 能力领先
Spring AI Java 企业级标准,可观测优先 企业采用率领先

三者不是竞争,是分工协作:LangChain 探路 → LangChain4J 快速跟进 → Spring AI 企业级封装。


七、避坑指南(2026 版)

1. 常见问题

问题 解决方案
API Key 管理混乱 用 Spring Cloud Vault 或配置中心,禁止硬编码
Token 消耗失控 启用 Actuator,配置预算告警,用 maxTokens 限制
RAG 效果不好 调整 Top-K、相似度阈值、分块策略,换 Embedding 模型
响应慢 流式响应,用小模型处理简单请求,预热连接
幻觉问题 RAG + 严格系统提示,设置”无法回答”的 fallback
国产模型不稳定 多模型备份,配置 fallback chain

2. 最佳实践

  1. 用 ChatClient,别直接用 ChatModel:ChatClient 封装更好,Advisor 链式处理
  2. RAG 用 QuestionAnswerAdvisor:3 行代码搞定,别手动拼接上下文
  3. Function 定义清晰@Description 写清楚用途和参数,帮助 LLM 正确调用
  4. VectorStore 选型:原型 Chroma,生产 Milvus/Qdrant,小数据 Redis/pgvector
  5. Observability 必开:上线前先配好,AI 调用必须有追踪
  6. 国产模型合规:数据不出境,用阿里/百度/讯飞,成本可控

3. 生产部署 Checklist

  • [ ] API Key 从配置中心/Vault 获取
  • [ ] Observability 开启,Token 消耗监控
  • [ ] 熔断降级配置(AI 调用失败 fallback)
  • [ ] 流式响应(降低首字延迟)
  • [ ] 日志脱敏(Prompt 可能含敏感信息)
  • [ ] VectorStore 持久化配置
  • [ ] 多模型备份(OpenAI 备通义,反之亦然)

总结

Spring AI 已经是 Java 企业级 AI 应用的事实标准:

维度 Spring AI 优势
成熟度 1.0 GA 近一年,API 稳定,生产验证
生态融合 Spring Boot/Cloud/Security/Actuator 一体化
企业级特性 Observability、配置管理、安全审计开箱即用
国产支持 阿里/百度/讯飞官方支持,合规可控
RAG 简洁 QuestionAnswerAdvisor 3 行代码搞定
MCP 支持 1.0+ 原生支持,工具生态繁荣

一句话:Spring 项目做 AI 应用,Spring AI 是唯一合理的选择。LangChain4J 在 Agent 方面领先,但企业级可观测性,Spring AI 完胜。

如果你是 Spring 开发者,想做 AI 应用,现在就是最好的时机——Spring AI 已经成熟,文档完善,社区活跃,生产就绪。


参考资料