AI agent开发指南

具备前端或全栈实战经验的开发者，核心目标是将Agent能力无缝融入真实业务场景，涵盖对话界面、知识库及工作流编排，而非深入算法研究。学习路径融合原理笔记、动手实验及本地问答目录，并交叉引用前后端技术。

写作形式围绕理论梳理与实操验证展开，并提供本地Q&A子目录，与前后端技术点形成交叉参考。

---

模块地图

编号	主题	本地目录	状态
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 核心概念

1. 大模型是什么：预训练 → 指令对齐 →（可选）微调
2. Token、上下文窗口、上下文长度与成本
3. Temperature、Top-p、Top-k：随机性与可控性
4. 幻觉：成因、grounding、引用溯源
5. 开源 vs 闭源：Llama、Qwen、DeepSeek、GPT、Claude 等选型维度
6. AIGC 能力谱系：文本 / 代码 / 多模态（了解）

1.2 Prompt 工程

1. System / User / Assistant 消息结构
2. Few-shot、Zero-shot、Chain-of-Thought
3. 结构化输出：JSON Mode、Function Calling、Pydantic 约束
4. Prompt 模板化与版本管理
5. 常见反模式：指令冲突、上下文污染、过度约束

1.3 动手目标

1. 用任意 API 实现：摘要、分类、抽取三类任务
2. 对比同一任务在不同 Prompt 下的稳定性

---

2. LLM API 与模型选型

2.1 API 使用

1. OpenAI 兼容接口（OpenAI / Azure / 国内大模型开放平台）
2. Anthropic Messages API（了解）
3. 流式输出：SSE chunk 解析（衔接 front §10 SSE）
4. 错误处理：限流、超时、重试、fallback 模型
5. 成本估算：input/output token 计费

2.2 模型选型

1. 按场景：通用对话 / 代码 / 长上下文 / 推理
2. 按部署：云端 API vs 本地私有化
3. Embedding 模型选型（与 RAG 强相关）
4. 评测维度：准确率、延迟、成本、合规

2.3 动手目标

1. 封装统一的 LLM Client（支持流式 + 重试 + 多模型路由）

---

3. RAG 检索增强生成

3.1 知识流水线

1. 文档解析：PDF / Word / Markdown / HTML / 表格
2. 分块策略：chunk size、overlap、按标题 / 语义切分
3. Embedding 与向量库：OpenAI / BGE / M3E；Milvus / pgvector / Chroma
4. 检索：向量检索、关键词（BM25）、混合检索
5. 增强：Rerank、HyDE、查询改写、多路召回
6. 生成：上下文注入、引用标注、拒答策略

3.2 评估与迭代

1. 检索质量：Recall@K、MRR
2. 生成质量：faithfulness、人工抽检
3. bad case 分析 → 调 chunk / 调 prompt / 补数据

3.3 主流工具

1. LangChain Retriever / LCEL
2. LlamaIndex（数据连接器丰富）
3. 自研 pipeline（企业常见）

3.4 动手目标

1. 论文 / 文档阅读助手：上传 PDF → 问答 → 带页码引用
2. 人事 / 业务知识库：结构化 + 非结构化混合检索

---

4. Agent 与工具调用

4.1 设计模式（主流）

1. ReAct：推理 ↔ 行动交替
2. Plan-and-Execute：先规划再逐步执行
3. Reflection：自我 critique、失败重试
4. Tool Use / Function Calling：模型决定调哪个工具、传什么参数

4.2 工具设计

1. Schema 定义：名称、描述、参数类型（描述质量决定调用成功率）
2. 工具原则：幂等、最小权限、可观测、错误信息可读
3. 与后端 API 对接（衔接 backend/all.md §9）
4. 代码执行：沙箱（Docker / E2B / WASM）

4.3 记忆

1. 短期：对话上下文、滑动窗口、摘要压缩
2. 长期：向量记忆、用户偏好、会话持久化（Redis / DB）

4.4 动手目标

1. 订单 / 表格查询助手：自然语言 → SQL 或 API 调用 → 结构化回复
2. 至少实现：查知识库 + 调 REST API 两个 Tool

---

5. 应用框架

5.1 LangChain 核心

1. Model I/O：Prompt Template → LLM → Output Parser
2. Chain / LCEL 组合
3. Memory、Retriever、Agent Executor
4. Callbacks 与调试

5.2 LangGraph（2024–2026 主流 Agent 编排）

1. 有状态图：节点、边、条件分支
2. 循环与人工介入（Human-in-the-loop）
3. 与 CrewAI、AutoGen 的定位对比（了解）

5.3 其他

1. LlamaIndex：索引类型、Query Engine
2. Semantic Kernel（.NET / 跨语言，了解）
3. 低代码：Dify、Coze、FastGPT 的工作流模型

5.4 动手目标

1. 用 LangGraph 实现一个带分支的 RAG + Agent 工作流
2. 用 Gradio / Streamlit 快速搭 Demo UI

---

6. 模型部署与本地推理

6.1 推理基础

1. Transformer 架构（自注意力、Encoder/Decoder）— 理解即可
2. GPT（生成式）vs BERT（理解式）vs T5（了解）
3. 量化：INT8 / INT4、GGUF、AWQ、GPTQ
4. 显存估算：参数量 × 精度 ≈ 占用

6.2 部署方案（主流）

1. Ollama：本地一键拉模型、OpenAI 兼容端点
2. vLLM / TGI / llama.cpp：生产级吞吐
3. LM Studio：本地 GUI 调试
4. HuggingFace Hub：模型下载、Transformers pipeline
5. Qwen / Llama / DeepSeek 等开源模型部署与量化

6.3 Embedding 部署

1. Ollama Embedding、本地 BGE
2. 与 RAG pipeline 联调

6.4 动手目标

1. Ollama 部署 Qwen2 + OpenAI SDK 调用
2. 对比云端 API vs 本地模型的延迟与质量

---

7. 微调（按需深入）

7.1 方法

1. 全量微调 FFT（成本高，少做）
2. 参数高效微调 PEFT：LoRA、QLoRA、Adapter
3. 指令微调 vs 继续预训练（了解）
4. 显存优化：梯度检查点、DeepSpeed、Flash Attention

7.2 工具链

1. HuggingFace PEFT / TRL
2. LLaMA-Factory：界面化微调（主流入门）
3. Unsloth、ms-swift（ModelScope）
4. 数据集格式：Alpaca、ShareGPT、JSONL

7.3 评估

1. loss 曲线、验证集 perplexity
2. 业务指标：人工评测、A/B 对比 base 模型

7.4 动手目标（选做）

1. Qwen2 小数据集 LoRA 微调（如客服话术 / 金融术语）
2. 命名实体识别（NER）或语义相似度任务（分类 / 匹配类）

---

8. 多 Agent 与 MCP

8.1 多 Agent

1. 四大模式：Reflection、Tool Use、Planning、Multi-Agent
2. 任务 DAG、依赖驱动编排、并行执行
3. 角色分工：规划者 / 执行者 / 审查者
4. 执行-反思闭环（Reflect Loop）
5. 本地详解：多 Agent 通用原理 — 详解
6. 参考架构：[Claude Code 架构](./Claude Code架构.md)

8.2 MCP（Model Context Protocol）

1. Server / Client / Resources / Tools / Prompts
2. 与 Function Calling 的关系：MCP 是工具层的标准化协议
3. 自写 MCP Server 暴露业务 API / 文件 / 数据库

8.3 框架对照

框架	特点	适用
LangGraph	图编排、状态机、可循环	复杂 Agent 工作流
CrewAI	角色 + 任务分工	多角色协作原型
AutoGen	对话式多 Agent	研究 / 原型
自研 Orchestrator	完全可控	企业生产平台

8.4 动手目标

1. 手写最小 Orchestrator：任务拆分 → 子 Agent 并行 → 汇总
2. 为一个内部 API 编写 MCP Server

---

9. 平台工程与生产化

9.1 Agent 平台（Dify 类）

1. 工作流引擎：节点、分支、变量、子流程
2. 对话应用 vs 工作流应用
3. 知识库管理、Skill / Plugin 注册
4. 模型路由、多租户、权限
5. SSE 流式编排（衔接 front UI + backend SSE 端点）

9.2 生产化 checklist

1. Prompt Caching / KV Cache：降本增效
2. 限流、配额、成本监控
3. 安全：Prompt 注入、工具越权、数据外泄、输出审核
4. 可观测：LangSmith / Langfuse / 自研 trace；每步输入输出可回溯
5. 评测：回归用例集、红队测试、线上 bad case 闭环
6. 版本：Prompt / 知识库 / 工作流版本管理与灰度

9.3 与前后端衔接

层	职责	索引
前端	对话 UI、流式 Markdown、文件上传	front/all.md §10
后端	BFF、SSE、鉴权、业务 API、向量库	backend/all.md §9
Agent	编排、RAG、Tool、模型路由	本目录

---

10. 实战案例

10.1 通用 Demo（练手）

1. 课程助教机器人（RAG + 对话）
2. 论文阅读助手（PDF RAG + 引用）
3. 本地知识库 + Ollama + Dify 聊天机器人

10.2 领域案例（结合金融业务）

1. 金融文档知识库问答（私有 PDF → 指标抽取 → 可检索）
2. 金融问句语义相似度（匹配 / 去重）
3. 信托产品净值查询 + AI 解读报告（三阶段串联，见 outline.md）

10.3 企业 Agent 平台（个人项目方向）

1. 业务人员配置工作流、统一对话入口
2. Skill 复用、SSE 编排、与现有 Spring Boot 后端集成
3. 踩坑记录：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

---

该模块地图系统梳理了从大模型基础到生产化落地的全链路技术，涵盖Prompt、RAG、Agent及工程实践，配合阶梯式里程碑与领域案例，可有效引导开发者构建端到端的AI Agent应用能力。