摘要

学 AI Agent 开发最大的困扰,往往不是学不会某一个框架,而是网上的教程东一榔头西一棒子——今天看一篇 RAG 的博客,明天看一个 LangGraph 的 demo,始终拼不出一张完整的技术地图。跟着 Claude Code 系统学习了一段时间 Agent 开发之后,我用 IT 运维/SRE(AIOps)场景做了一个练手项目——AIOps-example,把从最基础的 RAG 到企业级多智能体网关的 9 种架构模式,全部放在同一套业务场景、同一套基础设施上,做成了 9 个可以独立跑起来的例子。项目已经开源:github.com/robin-2016/AIOps-example。

是什么

AIOps-example 是一个"AI 工程架构模式展示仓库",场景选的是模拟的 IT 运维/SRE 场景:故障处置手册(runbook)、历史工单、告警、变更记录——这些数据全部是确定性生成的模拟数据,不连接任何真实生产系统,可以放心跑、放心改。

仓库按照架构复杂度递进,分成 9 个顶层目录,每一个都是独立可运行的示例:

每个子项目都是独立的 uv workspace member,有自己的 pyproject.toml、Python 包和 tests/,子项目之间从不互相 import 代码——即便有可复用的逻辑,也是刻意复制而不是共享,让每个目录保持独立、可以单独读懂。

核心优势

比起零散的单点教程,这个仓库的价值在于把"架构模式的差异"做成了可以直接对比的东西,而不是停留在概念层面:

• 同一场景,横向可比:所有 9 个模式共享同一个 IT 运维业务领域和同一套基础设施,想知道"朴素 RAG 和混合检索到底差多少"“LangGraph 和 CrewAI 写同一个任务代码量差多少”,直接跑一遍、看对比报告就知道,不用脑补。
• 不是玩具代码,有完整工程规范:每个 FastAPI 服务都遵循同一套 DI 模式——create_app(资源) -> FastAPI 纯函数负责测试注入,create_default_app() 单独负责构造真实的 Qdrant/Ollama/Langfuse/Postgres 客户端;异常处理统一返回固定中文提示,绝不向客户端泄露原始异常(包括绝不把沙箱里 LLM 生成的代码泄露出去)。
• 可观测性一路贯穿:所有 LLM/Agent 调用接入 Langfuse 追踪,服务级指标接入 Prometheus + Grafana,不是"能跑就行",而是能看到每一跳发生了什么、花了多少 token、多少延迟。
• 完全本地化,没有 API Key 门槛:全部使用本地 Ollama 做 LLM 推理和 embedding,不依赖任何外部大模型 API,适合边学边跑、反复实验而不用担心账单。
• 测试哲学清晰:单元测试 mock 掉 LLM/Qdrant/Postgres,CI 只跑这部分(pytest -m "not integration");每个子项目额外有一组 @pytest.mark.integration 测试验证真实基础设施下的端到端行为,只能手动跑,职责分得很干净。
• 从简单到复杂,循序渐进:目录编号本身就是一条学习路径——从 LCEL 基础链,到混合检索,到有状态多智能体,到协议化工具集成,到框架横向对比,到沙箱化代码执行,每一步的复杂度增量都是可感知的。

面向人群

• 正在系统学习 AI Agent 工程实践的开发者:想要一张完整的技术地图,而不是被动接受东拼西凑的知识碎片。
• 想选型的技术负责人:需要在 LangGraph、Smolagents、CrewAI、AutoGen 之间做选择,07-framework-comparison 直接给出同一任务下的定量对比。
• 关注生产可用性的工程师:关心 HITL 人工审批、多租户隔离、限速审计、沙箱执行这些"上生产前必须想清楚"的问题,而不只是"模型能不能回答对"。
• 不想为学习成本买单的个人开发者:全套本地 Ollama 推理,不需要 OpenAI/Anthropic API key 就能把 9 个模式全部跑起来。

不太适合只想"复制粘贴一段 RAG 代码就跑"的场景——这个仓库的价值恰恰在于把架构差异讲清楚,如果只需要最简单的检索链,直接看 01-foundations-rag 一个目录就够了。

如何使用

环境准备

# 前置条件:Python 3.12+、uv、Docker + Docker Compose、本地运行的 Ollama
ollama pull qwen2.5:7b     # 对话模型
ollama pull bge-m3         # embedding 模型

git clone https://github.com/robin-2016/AIOps-example.git
cd AIOps-example

# 把所有 workspace member 装进同一个共享虚拟环境
uv sync

# 复制并按需调整环境变量(Ollama 地址/模型名、Qdrant 地址、Langfuse key 等)
cp .env.example .env

跑单元测试(不需要 Docker/Ollama)

uv run pytest -m "not integration"

跑一个具体子项目

每个子项目都遵循同样的三步套路:启动它需要的 docker compose 服务 → 如果有索引/数据生成脚本就先跑一遍 → 启动它的 FastAPI 服务。以 03-langgraph-agents(LangGraph 智能体,含人工审批)为例:

docker compose up -d qdrant agent-state
cd 03-langgraph-agents && uv run python scripts/index.py
uv run uvicorn langgraph_agents.app:create_default_app --factory --port 8003

如果想看多智能体框架的横向对比,07-framework-comparison 直接跑脚本即可:

docker compose up -d qdrant
cd 07-framework-comparison && uv run python scripts/index.py
uv run python compare.py   # 输出 LangGraph/Smolagents/CrewAI/AutoGen 的延迟、Token 数、代码量对比

打开可观测性面板

# Langfuse:追踪每一次 LLM/Agent 调用
docker compose up -d postgres clickhouse redis minio langfuse-web langfuse-worker
# UI: http://localhost:3000

# Grafana:服务级指标可视化(数据源和 dashboard 已通过 provisioning 自动配置)
# UI: http://localhost:3001，Prometheus UI: http://localhost:9092

每个子项目具体的端口、curl 示例和详细说明,仓库里的 docs/RUNNING_CN.md 都有完整记录;每个子项目的设计文档和实施计划也分别保存在 docs/superpowers/specs/ 和 docs/superpowers/plans/ 下,想了解某个模式的设计取舍,直接翻对应文档就行。

项目完全开源,License 是 MIT,欢迎 star、fork、提 issue:github.com/robin-2016/AIOps-example