AI大模型应用开发全家桶：LLM、RAG、Agent、MCP与工作流实战

如果你正准备入门 AI 大模型应用开发，先别急着背 Prompt。这次我们来看的是一套覆盖面很广的“免费全家桶”学习路线：LLM 基础调用、RAG 知识库、Agent 智能体、MCP 工具协议、工作流编排、工具调用，一条链路全部打通。更难得的是，整套教程的后端工程同时给了 FastAPI（Python）和 Spring Boot（Java）两个版本，适合不同技术栈的开发者对照学习。

这类全家桶的价值不在于某个单点功能，而在于它把“模型能力”和“工程能力”拼在了一起。你既能学会用 LangChain、LangGraph、向量数据库做 RAG，也能看到 Agent 如何调用外部工具，还能理解 MCP 如何统一模型与工具之间的通信。本文会按模块拆解这套学习路线，给出环境准备、代码示例、接口封装、批量任务设计和问题排查思路。无论你是后端开发、算法工程师，还是准备做 AI 应用的独立开发者，都可以先收藏再用。

1. 核心能力速览

我们先看这套内容的能力边界。由于教程的发布时间和仓库内容会持续更新，以下是基于标题信息整理的能力速览，具体细节以你实际获取的版本为准。

从这套内容里，你能沉淀下来的不是“看一遍就忘”的代码，而是一套可以复用的工程骨架：模型服务统一封装、文档入库流水线、工具注册表、流程编排器。这些模块无论未来模型怎么换，骨架都不会过时。

2. 适用场景与使用边界

2.1 适合谁看

如果你符合下面任一情况，这套全家桶值得花时间跟一遍：

• 你是后端开发，已经熟悉 FastAPI 或 Spring Boot，想快速把大模型能力接入业务系统。
• 你是算法工程师，模型调优做了不少，但面向真实业务的 API 封装、状态管理等工程环节比较薄弱。
• 你是独立开发者，想用 RAG、Agent、工作流做一个完整产品原型。
• 你所在团队需要一套内部 AI 应用的起步代码规范，希望统一 Chat 接口、统一工具调用方式。

2.2 不适合什么场景

不建议把这套内容当作“纯 Prompt 技巧大全”。它更侧重工程实现，如果你只想要提示词模板，可以跳过大部分代码部分。

另外，这套内容解决的是“应用层开发”，不是模型训练。不要指望看完之后能微调出一个 7B 模型。它关注的是：如何把已有的模型能力变成稳定、可调、可维护的服务。

2.3 使用边界与合规提醒

大模型应用开发涉及几个容易踩线的点：

• 文档和知识库数据必须有合法来源，不要随意抓取他人网站文本入库。
• 如果 RAG 内容涉及个人信息、企业内部资料，要做好权限隔离。
• Agent 调用外部工具前，必须确认工具的使用授权，避免未经授权的账号操作。
• 涉及人脸、声音、肖像生成等功能时，必须获得当事人明确授权。
• 对外提供服务时，需要增加输入输出审核机制，防止生成违法或攻击性内容。

这些合规要求不是“上生产再说”，而是在设计阶段就要写进系统里。

3. 技术路线图：LLM、RAG、Agent、MCP、工作流怎么串起来

这套全家桶的学习顺序，基本就是一条从简到繁、从单次调用到多步骤编排的路线：

3.1 第一阶段：LLM 基础调用

先掌握最基本的聊天补全接口。无论是调用 OpenAI 兼容接口，还是本地部署的 Ollama、vLLM，本质上都是把 messages 数组发给模型，拿到返回内容。这一阶段的核心知识点包括 Prompt 设计、temperature、max_tokens、流式输出等。

3.2 第二阶段：RAG 检索增强生成

RAG 解决的是“模型不知道你私有数据”的问题。流程是：加载文档、切片、向量化、存入向量库；用户提问时先检索相关片段，再把片段作为上下文拼进 Prompt，最后由模型生成答案。

这一阶段需要掌握文档解析、文本切片策略、向量化模型选择、向量库检索和重排。这也是全家桶里工作量最大的模块。

3.3 第三阶段：Agent 与工具调用

Agent 的核心是让模型决定“下一步做什么”。模型返回工具调用指令，代码去执行工具，再把执行结果回填给模型，形成循环。你可以做一个天气查询 Agent、SQL 查询 Agent、文件操作 Agent。

工具调用不是魔法，关键是设计一套工具描述规范，让模型知道有哪些工具、每个工具的参数是什么、什么条件下调用。

3.4 第四阶段：MCP 模型上下文协议

MCP 像是“Agent 时代的 USB 接口”。它把各种工具、数据源、文件系统统一成标准协议，模型或 Agent 通过 MCP 客户端发现并调用服务端暴露的工具。这样做的好处是，工具提供方只需要实现一次 MCP Server，就能被多个 AI 应用复用。

3.5 第五阶段：工作流编排

当单次 Agent 循环不够用，就需要工作流。你可以在代码里定义节点和连线：先意图识别，再走 RAG，然后调用工具，最后生成报告。工作流可以解决多步任务、条件分支、人工审批、超时重试等复杂场景。

4. 环境准备与前置条件

在开始之前，建议先按下面的清单准备环境。这只是一个通用清单，具体版本以教程实际要求为准。

环境变量示例：

bash复制# .env 示例，实际值需要按教程或自己的服务替换
MODEL_API_KEY=your-model-api-key
MODEL_API_BASE=https://your-model-gateway/v1
MODEL_NAME=your-model-name
VECTOR_DB_URL=http://localhost:6333
DATASET_DIR=./data/docs

如果使用本地模型，还需要准备足够显存的 GPU。以常见的 7B 量化模型为例，一般 8G 显存可以跑推理，但并发能力有限。因此，家里只有 4G 显存的老显卡，更稳妥的做法是先用云端 API 跑通流程，再考虑本地模型。

5. LLM 基础调用：FastAPI 与 Spring Boot 双版本实现

学习全家桶的第一步，是把 Chat 接口封装成自己的后端服务。这里给出两个版本的通用示例，实际项目需要按你的模型网关替换地址和参数。

5.1 FastAPI 版本

python复制from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class ChatRequest(BaseModel):
    model: str = "your-model-name"
    messages: list[dict] = []
    temperature: float = 0.7

class ChatResponse(BaseModel):
    reply: str

@app.post("/v1/chat/completions", response_model=ChatResponse)
async def chat_completions(req: ChatRequest):
    # 这里应该替换为调用你的真实模型服务
    # 例如使用 OpenAI SDK、Ollama SDK 或 requests 转发
    reply = "demo response"
    return ChatResponse(reply=reply)

这个例子里的 /v1/chat/completions 采用的是兼容 OpenAI 风格的路由。实际开发中，你可以在函数内部调用上游模型网关，也可以直接调用 vLLM、FastChat 提供的推理服务。再往上一层，可以加入流式输出支持，把模型返回的增量内容通过 SSE 推给前端。

5.2 Spring Boot 版本

java复制@RestController
@RequestMapping("/v1/chat")
public class ChatController {

    @PostMapping("/completions")
    public Map<String, Object> completions(@RequestBody ChatRequest request) {
        // 使用 RestClient 调用 OpenAI 兼容接口
        String response = RestClient.create()
                .post()
                .uri("https://your-model-gateway/v1/chat/completions")
                .header("Authorization", "Bearer " + request.getApiKey())
                .body(Map.of(
                        "model", request.getModel(),
                        "messages", request.getMessages(),
                        "temperature", request.getTemperature()
                ))
                .retrieve()
                .body(String.class);

        return Map.of("result", response);
    }
}

Spring Boot 版本的重点不在于模板代码，而在于统一封装。你可以定义一个接口 ChatClient，分别实现 OpenAiChatClient、OllamaChatClient、LocalHttpChatClient。这样切换模型服务时，业务代码不会大面积改动。

5.3 统一接口设计建议

不管用哪个框架，建议你的 Chat 接口都返回统一结构：

json复制{
  "code": 0,
  "data": {
    "reply": "模型返回内容",
    "usage": {
      "prompt_tokens": 120,
      "completion_tokens": 80
    },
    "trace_id": "uuid"
  },
  "message": "ok"
}

trace_id 尤其重要，后续排查线上问题、追踪一次 RAG 检索或 Agent 调用链路时，没有它只能靠猜。

6. RAG 知识库实战：文档加载、向量检索与问答

RAG 是整个全家桶里工程点最多的一块。完整流程如下：

1. 加载文档。
2. 文档清洗。
3. 文本切片。
4. 调用 Embedding 模型向量化。
5. 写入向量数据库。
6. 接收问题。
7. 问题向量化。
8. 向量检索候选片段。
9. 可选重排。
10. 构造 Prompt。
11. 调用 LLM 生成答案。

6.1 文本切片策略

切片直接影响检索质量。常见策略有三种：

• 固定长度切片：按 500 到 1000 个字符切成一段，配合重叠区间。
• 语义切片：按标题结构、段落边界切片，适合结构化文档。
• 递归字符切片：先按大分隔符切，再按小分隔符继续切，适合 Markdown、代码文件。

如果文档是 PDF，先做解析和 OCR 的准确率会显著影响后续效果。建议不要直接把扫描版 PDF 丢进 RAG 流程。

6.2 检索与问答的 Python 示例

下面的代码是伪代码，重点是还原流程。

python复制def rag_query(question: str) -> str:
    # 加载文档并切片
    docs = load_documents("data/docs")
    chunks = split_text(docs, chunk_size=800, overlap=100)

    # 离线阶段已经向量化入库，这里只做查询
    question_vector = embed(question)
    hits = vector_store.search(question_vector, top_k=5)

    # 构造上下文和 Prompt
    context = "\n\n".join([h["text"] for h in hits])
    prompt = f"""请基于以下资料回答用户问题。
资料：
{context}

问题：{question}
"""
    return chat_with_model(prompt)

在真实项目中，文档入库和在线检索应该是两个模块：离线定时任务负责增量更新向量库；在线接口只做查询。不要把 PDF 解析放到请求链路里，否则接口延迟会被拖到无法接受。

6.3 RAG 查询接口设计

建议提供两类接口：

• /v1/rag/query：只返回答案文本，适合聊天机器人。
• /v1/rag/query_detail：返回答案、命中的片段、来源文档和相似度分数，方便调试。

RAG 上线后需要持续观察一个指标：检索命中是否准确。不要只看最终答案好不好，因为如果检索不对，答案就是模型在“编”。在系统里打印每次检索命中的文档名和分数，是排查问题的第一步。

7. Agent 与工具调用：Function Calling 的工程实现

Agent 的关键不是“Agent”这个名词，而是工具调用机制。模型根据用户请求判断该调用哪个工具，并生成结构化参数，代码执行工具后把结果返回给模型。

7.1 工具描述示例

python复制tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "查询城市当前的天气情况",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "城市名称，例如北京、上海"
                    }
                },
                "required": ["city"]
            }
        }
    }
]

这个描述会让模型知道：存在一个 get_weather 工具，接收城市名。当用户问“北京今天冷吗”，模型会返回类似 {"name": "get_weather", "arguments": {"city": "北京"}} 的调用指令。

7.2 工具调用流程

一次完整的 Agent 工具调用循环包括：

1. 接收用户消息。
2. 把消息和工具描述一起发送给模型。
3. 模型返回 tool_calls。
4. 代码根据工具名称执行对应函数。
5. 把函数执行结果作为新的消息回填给模型。
6. 模型基于结果生成最终回复。

需要注意的是，工具执行可能会报错、超时或返回异常。最好给每个工具封装超时和错误返回结构，避免模型被错误信息误导。比如 get_weather 超时，应当返回“工具执行超时，无法获取天气信息”，而不是把堆栈信息直接传给模型。

7.3 Agent 后端框架

Python 端可以选择 LangChain、LangGraph、自己维护循环；Java 端可以使用 Spring AI 或自研工具注册表。无论哪个框架，核心都是一张工具注册表：

建议把工具权限纳入 Agent 设计：不是每个用户都能调用所有工具，尤其是删除、发送、支付类操作，必须校验会话权限。

8. MCP 接入：统一模型与工具的通信协议

MCP 的出现是为了解决工具生态碎片化问题。一个工具接入方实现 MCP Server 后，可以被支持 MCP 的 Agent 客户端动态发现和调用，不用在每家 Agent 里写定制代码。

8.1 MCP 的角色划分

• MCP Host：运行 Agent 或应用的进程。
• MCP Client：负责与 MCP Server 建立连接、发现工具、转发调用。
• MCP Server：暴露具体工具和数据源，例如数据库查询、文件读取、GitHub 操作。

比如你本地运行一个 MCP Server，提供 read_report 和 query_metrics 两个工具。支持 MCP 的 Agent 启动时会自动发现这两个工具，不需要为每个 Agent 单独开发插件。

8.2 一个简单的 MCP Server 配置示意

json复制{
  "servers": {
    "report-server": {
      "command": "python",
      "args": ["mcp_servers/report_server.py"],
      "env": {
        "REPORT_DIR": "./data/reports"
      }
    }
  }
}

在二次开发时，注意 MCP 规范版本更新较快，务必以教程或官方文档为准。先让“一个 Server 暴露一个工具、一个 Client 调用成功”，再逐步扩展。不要一开始就设计几十个工具的矩阵。

9. 工作流编排与批量任务设计

当单次 Agent 循环无法满足业务要求时，就进入工作流阶段。工作流更像一个有向图：每个节点是一个处理步骤，节点之间有条件和逻辑连线。

9.1 工作流节点类型

一个典型的“问答加报告生成”工作流可以是这样：用户输入问题 -> 判断是否需要检索 -> 检索资料 -> 调用 LLM 生成草稿 -> 调用工具生成 PDF -> 返回下载链接。

9.2 批量任务队列

如果是离线批量处理，不要让 HTTP 请求长时间占用连接。建议把任务拆成异步队列：

json复制{
  "task_id": "20250101-001",
  "status": "pending",
  "type": "rag_generate",
  "params": {
    "question": "总结本季度销售报告",
    "document_ids": ["doc_001", "doc_002"],
    "output_format": "markdown"
  }
}

Python 端可以使用 Celery、FastAPI BackgroundTasks 或 Dify 的工作流引擎；Java 端可以用 Spring Async、RabbitMQ 或 Temporal。关键是任务状态要落库，失败要有重试，长时间任务要有心跳。

9.3 异步处理示例

python复制from fastapi import BackgroundTasks

task_store = {}

@app.post("/v1/async/rag", status_code=202)
async def submit_rag(question: str, background_tasks: BackgroundTasks):
    task_id = uuid4().hex
    task_store[task_id] = {"status": "pending"}
    background_tasks.add_task(run_rag_task, task_id, question)
    return {"task_id": task_id, "status": "pending"}

@app.get("/v1/async/rag/{task_id}")
async def get_task(task_id: str):
    return task_store.get(task_id, {"status": "not_found"})

批量任务的常见坑是资源并发控制。如果同时提交 100 个任务，而模型服务只能并发 5 个请求，不要让队列一次性把模型服务打挂。要给队列加上最大并发数和超时熔断。

10. 资源占用与性能观察

10.1 显存与延迟

如果你使用本地模型，显存占用和推理延迟是绕不开的话题。需要重点观察：

• 加载模型后显存占用多少。
• 单次对话生成 500 字需要多久。
• 并发 2 个请求时延迟和显存如何变化。
• 向量化模型和生成模型是否共用显存。

这些数据需要在你自己的机器上实测，不同模型版本、量化方式、上下文长度差异很大。更稳妥的做法是：先用小模型、短上下文跑通整条链路，再逐步调大参数，记录性能拐点。

10.2 CPU 推理与 GPU 推理

CPU 可以跑推理，但适合延迟不敏感的离线任务。如果线上服务要求秒级响应，建议使用 GPU 或云端 API。RAG 链路里，向量化模型可以选用较小的 Embedding 模型，在 CPU 上也能跑得比较快。

10.3 降低显存占用的通用手段

• 使用量化模型，例如 4bit、8bit。
• 限制上下文长度，截断过长的对话记录。
• 减少批量并发。
• 使用流式输出，避免一次性生成超长内容。
• 向量数据库单独部署，避免和应用抢资源。

10.4 端口和进程

FastAPI 常用端口是 8000，Spring Boot 常用 8080。如果启动后页面打不开，优先检查端口是否被占用。

bash复制# Linux / macOS
lsof -i :8000

# Windows
netstat -ano | findstr :8000

如果端口冲突，可以换端口启动：

bash复制uvicorn main:app --host 127.0.0.1 --port 8001

bash复制java -jar app.jar --server.port=8081

11. 常见问题与排查方法

排查问题的通用原则是：先看日志，再复现请求，最后最小化测试。不要一上来就改代码。

12. 最佳实践与合规建议

12.1 工程实践

• 所有外部模型服务调用统一走网关，不要散落在业务代码中。
• 模型调用、RAG 检索、Agent 工具调用都要记录日志，至少包含请求参数、耗时、token 消耗和结果摘要。
• 先小参数测试，再上批量任务；先离线验证结果，再开放线上入口。
• 把文档目录、向量库索引、输出结果分开管理，建立固定目录结构。
• 接口服务默认只在本机监听，需要对外暴露时通过反代控制访问范围。
• 批量任务要设计失败重试和人工处理通道，避免任务失败后静默丢失。

12.2 合规实践

• 不要收集超出业务需要的用户数据。
• RAG 文档库必须确认数据来源合法。
• Agent 工具调用涉及第三方系统操作时，要使用最小权限账号并记录操作日志。
• AI 生成内容面向公开场景时，建议保留提示词、检索片段和模型版本等追溯信息。
• 本地部署不等于没有合规责任，生成内容的最终把关仍需要代码或人工参与。

13. 总结与下一步

这套“免费 AI 大模型应用开发全家桶”最值得尝试的点，是把 LLM、RAG、Agent、MCP、工作流、工具调用连成了一条完整的学习链路，而且同时给了 FastAPI 和 Spring Boot 双版本。你不需要从零设计系统架构，可以先跟着教程跑通最小闭环，再逐步替换成自己的业务。

第一步建议先跑通 /v1/chat/completions，把基础 Chat 接口吃透；第二步给系统加 RAG，让知识库生效；第三步再加一个工具调用 Agent。最容易踩的坑是“一口吃成一个胖子”，一上来就想把 Agent、MCP、工作流全部接入，结果每一步都停在表面。

下一步你可以根据自己的技术栈选择入口：Python 团队从 FastAPI 教程开始，Java 团队从 Spring Boot 教程开始，跑通之后再对照学另一个版本，理解两种框架在模型调用、批量任务和工作流设计上的异同。把这套骨架跑通，后面接任何新模型、新工具都只是换配置的事。