AI agent开发
作者：袖梨
2026-07-02
面向背景：有前端 / 全栈经验，目标是把 Agent 能力接入真实业务（对话 UI、知识库、工作流编排），而非做算法研究员。
写作形式：原理笔记 + 动手实验 + 本地 Q&A（ai/ 子目录，待建）+ 与前后端的交叉引用。
模块地图
| 编号 | 主题 | 本地目录 | 状态 |
|---|---|---|---|
| 1 | 大模型认知与 Prompt 工程 | 1. LLM-Prompt/ | 待写 |
| 2 | LLM API 与模型选型 | 2. LLM-API/ | 待写 |
| 3 | RAG 检索增强生成 | 5. RAG-Knowledge/ | 待写 |
| 4 | Agent 与工具调用 | 4. Agent-Practice/ | 待写 |
| 5 | 应用框架 | 3. LangChain/ | 待写 |
| 6 | 模型部署与本地推理 | 6. Deploy-Platform/ | 待写 |
| 7 | 微调（按需深入） | 7. Fine-Tuning/ | 待写 |
| 8 | 多 Agent 与 MCP | 8. Multi-Agent-MCP/ | 原理文已有 |
| 9 | 平台工程与生产化 | 9. Production/ | 待写 |
| 10 | 实战案例 | 10. Case-Study/ | 待写 |
推荐学习路线
Phase A 认知（1 Prompt → 2 API） ← 1–2 周，快速出 Demo
Phase B 应用（3 RAG → 4 Agent → 5 框架） ← 核心能力，与业务最近
Phase C 模型（6 部署 → 7 微调按需） ← 需要私有化或领域适配时深入
Phase D 工程（8 多 Agent / MCP → 9 生产化） ← 企业级落地
Phase E 案例（10 行业实战） ← 串联 front / backend
| 里程碑 | 完成标准 |
|---|---|
| M1 | 用 API 完成一个带流式输出的对话页（对接 front §10 SSE） |
| M2 | 完成 RAG 问答 Demo：文档上传 → 检索 → 带引用回答 |
| M3 | 完成单 Agent Demo：至少 2 个 Tool（查 API + 查知识库） |
| M4 | 本地部署 Qwen / Llama（Ollama 或 vLLM）+ Dify 工作流 |
| M5 | 读通 多 Agent 通用原理 并实现最小 Orchestrator |
| M6 | 一个端到端企业场景案例（金融知识库 + 工作流 + 前端 UI） |
1. 大模型认知与 Prompt 工程
1.1 核心概念
- 大模型是什么：预训练 → 指令对齐 →（可选）微调
- Token、上下文窗口、上下文长度与成本
- Temperature、Top-p、Top-k：随机性与可控性
- 幻觉：成因、grounding、引用溯源
- 开源 vs 闭源：Llama、Qwen、DeepSeek、GPT、Claude 等选型维度
- AIGC 能力谱系：文本 / 代码 / 多模态（了解）
1.2 Prompt 工程
- System / User / Assistant 消息结构
- Few-shot、Zero-shot、Chain-of-Thought
- 结构化输出：JSON Mode、Function Calling、Pydantic 约束
- Prompt 模板化与版本管理
- 常见反模式：指令冲突、上下文污染、过度约束
1.3 动手目标
- 用任意 API 实现：摘要、分类、抽取三类任务
- 对比同一任务在不同 Prompt 下的稳定性
2. LLM API 与模型选型
2.1 API 使用
- OpenAI 兼容接口（OpenAI / Azure / 国内大模型开放平台）
- Anthropic Messages API（了解）
- 流式输出：SSE chunk 解析（衔接 front §10 SSE）
- 错误处理：限流、超时、重试、fallback 模型
- 成本估算：input/output token 计费
2.2 模型选型
- 按场景：通用对话 / 代码 / 长上下文 / 推理
- 按部署：云端 API vs 本地私有化
- Embedding 模型选型（与 RAG 强相关）
- 评测维度：准确率、延迟、成本、合规
2.3 动手目标
- 封装统一的 LLM Client（支持流式 + 重试 + 多模型路由）
3. RAG 检索增强生成
3.1 知识流水线
- 文档解析：PDF / Word / Markdown / HTML / 表格
- 分块策略：chunk size、overlap、按标题 / 语义切分
- Embedding 与向量库：OpenAI / BGE / M3E；Milvus / pgvector / Chroma
- 检索：向量检索、关键词（BM25）、混合检索
- 增强：Rerank、HyDE、查询改写、多路召回
- 生成：上下文注入、引用标注、拒答策略
3.2 评估与迭代
- 检索质量：Recall@K、MRR
- 生成质量：faithfulness、人工抽检
- bad case 分析 → 调 chunk / 调 prompt / 补数据
3.3 主流工具
- LangChain Retriever / LCEL
- LlamaIndex（数据连接器丰富）
- 自研 pipeline（企业常见）
3.4 动手目标
- 论文 / 文档阅读助手：上传 PDF → 问答 → 带页码引用
- 人事 / 业务知识库：结构化 + 非结构化混合检索
4. Agent 与工具调用
4.1 设计模式（主流）
- ReAct：推理 ↔ 行动交替
- Plan-and-Execute：先规划再逐步执行
- Reflection：自我 critique、失败重试
- Tool Use / Function Calling：模型决定调哪个工具、传什么参数
4.2 工具设计
- Schema 定义：名称、描述、参数类型（描述质量决定调用成功率）
- 工具原则：幂等、最小权限、可观测、错误信息可读
- 与后端 API 对接（衔接 backend/all.md §9）
- 代码执行：沙箱（Docker / E2B / WASM）
4.3 记忆
- 短期：对话上下文、滑动窗口、摘要压缩
- 长期：向量记忆、用户偏好、会话持久化（Redis / DB）
4.4 动手目标
- 订单 / 表格查询助手：自然语言 → SQL 或 API 调用 → 结构化回复
- 至少实现：查知识库 + 调 REST API 两个 Tool
5. 应用框架
5.1 LangChain 核心
- Model I/O：Prompt Template → LLM → Output Parser
- Chain / LCEL 组合
- Memory、Retriever、Agent Executor
- Callbacks 与调试
5.2 LangGraph（2024–2026 主流 Agent 编排）
- 有状态图：节点、边、条件分支
- 循环与人工介入（Human-in-the-loop）
- 与 CrewAI、AutoGen 的定位对比（了解）
5.3 其他
- LlamaIndex：索引类型、Query Engine
- Semantic Kernel（.NET / 跨语言，了解）
- 低代码：Dify、Coze、FastGPT 的工作流模型
5.4 动手目标
- 用 LangGraph 实现一个带分支的 RAG + Agent 工作流
- 用 Gradio / Streamlit 快速搭 Demo UI
6. 模型部署与本地推理
6.1 推理基础
- Transformer 架构（自注意力、Encoder/Decoder）— 理解即可
- GPT（生成式）vs BERT（理解式）vs T5（了解）
- 量化：INT8 / INT4、GGUF、AWQ、GPTQ
- 显存估算：参数量 × 精度 ≈ 占用
6.2 部署方案（主流）
- Ollama：本地一键拉模型、OpenAI 兼容端点
- vLLM / TGI / llama.cpp：生产级吞吐
- LM Studio：本地 GUI 调试
- HuggingFace Hub：模型下载、Transformers pipeline
- Qwen / Llama / DeepSeek 等开源模型部署与量化
6.3 Embedding 部署
- Ollama Embedding、本地 BGE
- 与 RAG pipeline 联调
6.4 动手目标
- Ollama 部署 Qwen2 + OpenAI SDK 调用
- 对比云端 API vs 本地模型的延迟与质量
7. 微调（按需深入）
7.1 方法
- 全量微调 FFT（成本高，少做）
- 参数高效微调 PEFT：LoRA、QLoRA、Adapter
- 指令微调 vs 继续预训练（了解）
- 显存优化：梯度检查点、DeepSpeed、Flash Attention
7.2 工具链
- HuggingFace PEFT / TRL
- LLaMA-Factory：界面化微调（主流入门）
- Unsloth、ms-swift（ModelScope）
- 数据集格式：Alpaca、ShareGPT、JSONL
7.3 评估
- loss 曲线、验证集 perplexity
- 业务指标：人工评测、A/B 对比 base 模型
7.4 动手目标（选做）
- Qwen2 小数据集 LoRA 微调（如客服话术 / 金融术语）
- 命名实体识别（NER）或语义相似度任务（分类 / 匹配类）
8. 多 Agent 与 MCP
8.1 多 Agent
- 四大模式：Reflection、Tool Use、Planning、Multi-Agent
- 任务 DAG、依赖驱动编排、并行执行
- 角色分工：规划者 / 执行者 / 审查者
- 执行-反思闭环（Reflect Loop）
- 本地详解：多 Agent 通用原理 — 详解
- 参考架构：[Claude Code 架构](./Claude Code架构.md)
8.2 MCP（Model Context Protocol）
- Server / Client / Resources / Tools / Prompts
- 与 Function Calling 的关系：MCP 是工具层的标准化协议
- 自写 MCP Server 暴露业务 API / 文件 / 数据库
8.3 框架对照
| 框架 | 特点 | 适用 |
|---|---|---|
| LangGraph | 图编排、状态机、可循环 | 复杂 Agent 工作流 |
| CrewAI | 角色 + 任务分工 | 多角色协作原型 |
| AutoGen | 对话式多 Agent | 研究 / 原型 |
| 自研 Orchestrator | 完全可控 | 企业生产平台 |
8.4 动手目标
- 手写最小 Orchestrator：任务拆分 → 子 Agent 并行 → 汇总
- 为一个内部 API 编写 MCP Server
9. 平台工程与生产化
9.1 Agent 平台（Dify 类）
- 工作流引擎：节点、分支、变量、子流程
- 对话应用 vs 工作流应用
- 知识库管理、Skill / Plugin 注册
- 模型路由、多租户、权限
- SSE 流式编排（衔接 front UI + backend SSE 端点）
9.2 生产化 checklist
- Prompt Caching / KV Cache：降本增效
- 限流、配额、成本监控
- 安全：Prompt 注入、工具越权、数据外泄、输出审核
- 可观测：LangSmith / Langfuse / 自研 trace；每步输入输出可回溯
- 评测：回归用例集、红队测试、线上 bad case 闭环
- 版本：Prompt / 知识库 / 工作流版本管理与灰度
9.3 与前后端衔接
| 层 | 职责 | 索引 |
|---|---|---|
| 前端 | 对话 UI、流式 Markdown、文件上传 | front/all.md §10 |
| 后端 | BFF、SSE、鉴权、业务 API、向量库 | backend/all.md §9 |
| Agent | 编排、RAG、Tool、模型路由 | 本目录 |
10. 实战案例
10.1 通用 Demo（练手）
- 课程助教机器人（RAG + 对话）
- 论文阅读助手（PDF RAG + 引用）
- 本地知识库 + Ollama + Dify 聊天机器人
10.2 领域案例（结合金融业务）
- 金融文档知识库问答（私有 PDF → 指标抽取 → 可检索）
- 金融问句语义相似度（匹配 / 去重）
- 信托产品净值查询 + AI 解读报告（三阶段串联，见 outline.md）
10.3 企业 Agent 平台（个人项目方向）
- 业务人员配置工作流、统一对话入口
- Skill 复用、SSE 编排、与现有 Spring Boot 后端集成
- 踩坑记录：SSE 断连、上下文爆炸、工具幻觉、评测闭环
附录 A：主流技术栈速查
| 类别 | 主流选型 |
|---|---|
| 云端 API | OpenAI、Claude、通义、DeepSeek、Moonshot |
| 本地推理 | Ollama、vLLM、llama.cpp |
| RAG 向量库 | pgvector、Milvus、Chroma、Qdrant |
| 应用框架 | LangChain、LangGraph、LlamaIndex |
| 低代码平台 | Dify、Coze、FastGPT |
| 微调 | LLaMA-Factory、Unsloth、ms-swift |
| 工具协议 | Function Calling、MCP |
| 可观测 | Langfuse、LangSmith、OpenTelemetry |
