awesome-llm-apps：从可运行案例出发，掌握RAG与Agent工程实践

很多开发者学 LLM 应用开发前两周做的事几乎一模一样看框架文档、复制示例代码、调 API Key然后在第三个项目上卡住。卡住的原因往往不是不会写代码而是缺少一份“可运行、可对照、可改造”的完整参考。你需要的不是一个收藏夹而是一个能直接跑起来的项目集合。这也是我推荐 Shubhamsaboo/awesome-llm-apps 的原因。它不是一个只有 README 和 star 数的资源清单而是一个用真实案例把主流 LLM 应用形态串起来的开源仓库。从最简单的 Chatbot到 RAG 问答、Agent 自动化和工具调用你能在目录里找到对应的可运行项目然后照着跑通、再改造成自己的应用。这篇文章会讲清楚三件事这个仓库到底解决了什么痛点它里面的应用形态分别适合什么场景以及如何把其中一两个案例真正跑起来。如果你正处于“理论懂一些但还没有完整跑通过一个 LLM 应用”的状态这篇文章会比较适合你。1. 为什么 LLM 应用看起来容易做起来总是卡在“最后一公里”传统后端应用的特点是逻辑确定。输入一个用户 ID返回一条用户记录行为是可预期的Bug 也是可复现的。但 LLM 应用不一样它把很多不确定性引入了开发链路。比如你要做一个文档问答系统不是写一个 Prompt 就够了。你得先解决文档加载、文本切分、向量化、检索、重排、上下文组装、模型调用、流式返回、日志追踪这一整条链路。任何一个环节出问题用户体感都是“这个 AI 回答得很蠢”或者“回答完全不对”。更麻烦的是链路上的问题往往不是报错而是“能跑但效果不行”。真正让新手崩溃的还有配置层面的问题。API Key 没设置对报 401Context 太长触发 token 限制Embedding 模型换了一个向量维度不一致整个向量库不能用了LangChain 版本升级旧的 API 被删了代码跑不起来本地部署大模型时显存不够换精度又遇到输出质量下降。这些问题在教程里几乎不会提到但在真实项目里每一个都会遇到。这就是 awesome-llm-apps 这类项目存在的价值。它把已经跑通的完整项目放在你面前而不是给你一堆碎片化的代码片段。你不需要从零开始研究“RAG 到底应该怎么搭”你只需要找到对应案例把环境跑起来然后在这个基础上改。学习的起点一下子从“造轮子”变成了“拆轮子”。2. awesome-llm-apps 到底是什么一个按目录就能跑起来的 LLM 实践案例库awesome-llm-apps 是 GitHub 上的一个开源项目作者是 Shubham Saboo。它的定位从名字就能看出来一个收集高质量 LLM 应用案例的仓库。但它的特殊之处在于里面的案例不只是贴一段核心代码而是尽量以独立可运行的方式组织起来。从材料覆盖的技术栈来看这个仓库涉及 OpenAI、Anthropic、LangChain、LlamaIndex、RAG、Agent、MCP 等当前 LLM 应用开发中的主流方向。和很多“awesome”系列仓库相比它的维护节奏和案例更新速度都比较快社区贡献者也多。对一个想跟趋势的开发者来说这本身就是一个优点。我推荐的用法是把它当作“应用形态目录”来用。你想做一个聊天机器人就去目录里找 Chatbot 案例你想做私有知识库问答就去找 RAG 案例你想做自动执行任务的 Agent就去看 Agent 案例。每个案例之间不是孤立的而是可以互相组合的。比如你可以在 RAG 案例的基础上加上 Agent让模型先检索资料再根据资料调用工具完成某个动作。这个仓库也有它的边界。它不是一门体系化课程里面每个案例的深度参差不齐它也不是一个可以直接部署到生产的完整解决方案很多案例更接近可运行的 Demo。对初学者来说它是最好的“跑通第一个 LLM 应用”的素材库对进阶开发者来说它更多是“查某个技术选型长什么样”的参考。3. 从仓库里能学到什么Chatbot、RAG、Agent 与 MCP3.1 RAG 类应用让模型拥有可以检索的私有知识很多团队想做知识库问答最困惑的一点是“模型怎么可能知道我们公司的内部文档” RAGRetrieval-Augmented Generation检索增强生成就是解决这个问题的标准方案。它的思路是不把模型当成知识的存储介质而是让模型在回答问题时先检索外部知识再把检索结果拼进 Prompt 里让模型生成答案。在 awesome-llm-apps 里这类案例通常包含文档加载、文本切分、向量化、存储、检索和生成几个模块。你可以看到一个常识性的问题如何通过检索外部资料获得准确回答。RAG 相关案例是很多开发者进入 LLM 应用开发的第一个完整项目因为它的链路清晰、见效快而且可以直接迁移到业务场景中。3.2 Agent 类应用从“回答问题”到“完成工作”如果说 RAG 解决的是“让模型知道什么”Agent 解决的是“让模型做什么”。Agent 类应用的核心是让模型在一个循环里自主决策分析用户请求、选择工具、调用工具、观察结果、决定下一步行动。这类案例在仓库里的形态多种多样。有的是让模型查天气、查日历、发邮件有的是让模型自己写代码、执行代码、根据结果调整策略。它背后用到的是 Function Calling 或 Tool Calling 能力模型本身不执行工具但它能够输出结构化的调用指令由外部执行器去真正调用工具。3.3 MCP 与工具调用LLM 应用走向工程化的关键一步Agent 应用遇到的最大问题是“工具接入标准化”。每个工具都有不同的鉴权方式、不同的数据格式、不同的调用协议如果每个工具都单独写一套适配逻辑Agent 的工程实现会非常杂乱。MCPModel Context Protocol模型上下文协议就是在这种背景下出现的它的目标是让 LLM 应用通过统一方式连接外部工具、数据库和业务系统。你可以把它理解为 LLM 世界的“USB-C 接口”过去每个外设都有自己的专属接口现在通过统一标准一个接口可以连接多种设备。MCP 让工具可以以标准化的方式暴露给模型客户端从而降低 Agent 应用接入工具的复杂度。在社区案例中多 Agent 协作和 MCP 相关话题的热度持续上升。很多开发者已经意识到单纯调 API 聊天已经不是瓶颈真正的瓶颈是如何让模型可靠地使用外部工具。如果你在仓库里看到 MCP 相关案例值得花时间跑一遍这大概率是接下来一年里 LLM 应用最核心的工程方向之一。3.4 多模态与文档处理文本之外的能力扩展LLM 应用并不只是文本问答。文档解析、图片理解、音频转写、图像生成工作流等方向也逐渐成为 LLM 应用的一部分。仓库中这类案例通常会展示如何把不同模态的数据交给模型处理。比如你可以让模型读取一个 PDF 中的表格也可以让模型根据图片内容生成描述甚至可以在图像生成工作流中让 LLM 参与提示词优化。这类应用的价值在于解决真实业务中的“非结构化数据”问题。过去处理一份合同、一张票据需要写大量规则代码现在可以借助多模态模型直接理解内容再结合工作流把信息提取成结构化数据。这也是很多企业内部 LLM 应用落地的真实起点。4. 环境准备与前置条件4.1 基础运行环境在动手之前先确认你的机器环境。大多数 LLM 应用案例以 Python 为主所以你至少需要安装 Python 3.9 或更高版本并且能用 pip 安装依赖。Git 也是必需的用来克隆仓库。如果你准备完全使用云端 API比如 OpenAI、Anthropic一台普通开发机器就够了如果你想本地跑开源模型建议准备一块显存足够的 GPU。具体版本要求请以仓库里单个案例的 requirements.txt 为准这里不给死版本号因为不同案例更新时间不同依赖差异很大。4.2 API Key 与模型配置大多数案例需要配置 API Key。社区项目最常见的做法是使用.env文件保存密钥然后在代码中通过dotenv加载。配置方式通常是这样的OPENAI_API_KEYsk-你的密钥如果你不想用 OpenAI很多案例也支持替换为其他模型的接口。使用兼容 OpenAI 格式的本地推理服务再常见不过你需要把 Base URL 指向本地服务比如OPENAI_API_BASEhttp://localhost:8000/v1千万要注意.env文件一定不能提交到 Git 仓库。包含密钥的文件一旦被公开很快会被爬虫扫描到导致密钥被滥用。4.3 向量数据库与本地依赖RAG 相关案例通常依赖向量数据库。常见的选型有 Chroma、FAISS、Qdrant 等。以 Chroma 为例安装时要注意它和 LangChain 的版本兼容性。如果你在安装过程中遇到编译报错可以先搜索一下对应的依赖版本再决定是否使用虚拟环境隔离。建议每个案例都创建独立的 Python 虚拟环境避免全局环境被不同版本的依赖污染。python -m venv .venv source .venv/bin/activate # Windows 下使用 .venv\Scripts\activate5. 完整示例跑通一个基于 RAG 的本地问答应用下面我们用一段通用代码演示 RAG 应用的核心链路。这个例子不直接对应仓库里的某个具体文件而是对常见 RAG 案例的最小化复现。你可以在理解它之后再去仓库里对照真实案例。5.1 安装依赖假设你已经创建了虚拟环境先安装以下依赖pip install python-dotenv langchain langchain-openai langchain-community chromadb pypdf这些库的作用分别是读取.env文件、提供 LangChain 核心能力、提供 OpenAI 接口、提供社区集成组件、提供向量数据库、解析 PDF 文件。5.2 准备一个测试 PDF为了让示例能跑通你需要准备一个 PDF 文件放在项目的docs目录下。这里不限制内容随便找一份你手头的资料即可。示例代码会读取这个 PDF把它切分成文本块建立向量索引。5.3 编写核心代码创建rag_app.py文件# 文件路径rag_app.py from pathlib import Path from dotenv import load_dotenv from langchain.chains import RetrievalQA from langchain_community.document_loaders import PyPDFLoader from langchain_community.vectorstores import Chroma from langchain_openai import ChatOpenAI, OpenAIEmbeddings from langchain_text_splitters import RecursiveCharacterTextSplitter load_dotenv() PDF_PATH ./docs/sample.pdf PERSIST_DIR ./data/chroma_db def build_vector_store(): 读取 PDF切分文本并写入向量库。 loader PyPDFLoader(PDF_PATH) documents loader.load() splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap50, ) chunks splitter.split_documents(documents) embeddings OpenAIEmbeddings() vector_store Chroma.from_documents( documentschunks, embeddingembeddings, persist_directoryPERSIST_DIR, ) return vector_store def ask_question(query: str) - str: 从向量库检索并生成答案。 embeddings OpenAIEmbeddings() vector_store Chroma( embedding_functionembeddings, persist_directoryPERSIST_DIR, ) qa RetrievalQA.from_chain_type( llmChatOpenAI(modelgpt-4o-mini, temperature0), retrievervector_store.as_retriever(search_kwargs{k: 4}), ) result qa.invoke(query) return result[result] if __name__ __main__: print(正在构建向量库...) build_vector_store() print(向量库构建完成开始提问) answer ask_question(这份文档的核心观点是什么) print(回答, answer)这段代码的核心逻辑有三步。第一步用PyPDFLoader读取 PDF第二步用RecursiveCharacterTextSplitter把文档切成 500 字符左右的小块块之间保留 50 字符的重叠这样可以减少上下文被切断导致的信息丢失第三步用OpenAIEmbeddings把文本块向量化写入 Chroma 向量库。提问时代码先将问题向量化在向量库中检索最相似的 4 个文本块再把问题和文本块组装成 Prompt 交给模型生成答案。temperature0是为了让答案更稳定减少随机输出。这里你需要注意如果使用的是兼容 OpenAI 的本地服务模型名称要改成你本地实际拉取的模型名例如qwen2.5:7b。5.4 配置.env在项目根目录创建.env文件OPENAI_API_KEYsk-你的密钥如果你使用本地兼容接口需要再加上OPENAI_API_BASEhttp://localhost:8000/v15.5 运行应用python rag_app.py第一次运行会创建向量库所以需要一些时间。你会看到终端输出“正在构建向量库...”以及“向量库构建完成开始提问”最后输出模型的回答。6. 运行结果与效果验证如果一切正常你会看到类似下面的输出具体答案取决于你的 PDF 内容正在构建向量库... 向量库构建完成开始提问 回答 这份文档主要讨论了...这里的判断标准并不是“答案是否完美”而是三点第一流程是否完整走通没有报错。第二回答是否基于你上传的文档内容而不是模型凭常识编造。第三当你在不同文档上复用时结果是否会随文档内容变化。如果运行失败第一步应该看终端报错信息。最常见的错误是连接 API 超时、API Key 无效、模型不存在以及向量库持久化目录冲突。如果报错信息指向langchain某个类不存在大概率是版本不匹配可以先检查pip list中的 LangChain 版本再对照官方文档调整 API 写法。7. 常见问题与排查思路问题现象可能原因排查方式解决方案调用 API 报 401API Key 未配置或已失效检查.env内容和环境变量重新生成 Key确认load_dotenv()生效安装依赖时编译失败某些包依赖本地编译工具链查看错误日志中的包名选择预编译 wheel 版本或升级 Python 版本向量库查询时报维度不一致Embedding 模型更换或配置错误检查当前 Embedding 模型输出维度删除旧向量库重新构建或统一 Embedding 模型回答明显与文档无关检索召回偏差或 Context 被截断打印检索到的文本块调整chunk_size、k参数或更换检索策略输入过长报 token 超限Prompt 超过模型上下文窗口统计 Prompt 长度切分文档、压缩上下文或换长上下文模型本地模型输出质量不稳定精度或量化配置不适合当前任务对比不同精度的输出在显存允许范围内优先使用更高精度例如从 8-bit 量化切回 FP16 或 BF16同一段代码别人能跑通你跑不通依赖版本不同对比requirements.txt和运行日志锁定版本使用虚拟环境关于精度问题多说一句。如果你在本地部署模型可能遇到过 FP16、FP32、BF16 这几个概念。FP32 精度高但显存占用大FP16 显存占用减半但在某些训练场景下容易数值溢出BF16 的指数范围更接近 FP32深度学习场景下通常更稳定。以 7B 模型为例FP16 部署大约需要 14GB 显存如果你的显卡只有 12GB就需要考虑量化方案。精度选择直接影响输出质量和显存占用这是本地部署绕不开的功课。8. 最佳实践与工程建议8.1 先跑通再改造拿到一个 LLM 案例第一件事不是逐行读代码而是先把环境配好、把应用跑起来。跑通之后你才具备改造的基础。改的时候一次只改一个变量。比如先改chunk_size观察回答质量变化再改检索数量k看答案是否更聚焦。如果不做对比实验你对参数的影响不会有真正的体感。8.2 注意 API Key 与数据安全LLM 应用开发中最容易被忽视的是安全边界。API Key 必须放在环境变量或.env文件中禁止写死在代码里更禁止提交到公开仓库。如果你处理的是企业内部文档要特别注意数据是否允许发送给第三方模型服务。合规性要求高的场景应该优先选择本地部署模型或者在数据出口做好脱敏。8.3 选择适合自己的编排框架LangChain、LlamaIndex、Spring AI这些框架解决的问题类似但侧重点不同。LangChain 核心价值在于编排能力适合快速搭建 RAG、Agent 链路LlamaIndex 对索引和检索做了更深封装更适合知识库类应用Spring AI 的优势是为 Java 技术栈团队提供统一的 LLM 应用开发方式。不要盲目追新选择一个团队熟悉、文档完善、社区活跃的框架更重要。8.4 上下文组织是 RAG 质量的隐藏变量很多 RAG 应用效果不好问题不在向量库而在上下文组织。检索到的文本块如果包含大量重复信息、或者顺序混乱模型很难给出高质量回答。实际工程中可以加入重排序环节用专门的 rerank 模型对召回结果打分也可以在 Prompt 中明确告诉模型“如果资料中没有答案请直接说不知道”减少幻觉。8.5 从 Demo 到生产还需要补齐工程能力仓库里的大多数案例是 Demo而不是生产系统。从 Demo 到生产你需要补齐缓存、日志、监控、评测、成本控制和多版本回滚能力。LLM 应用的输出是非确定性的所以评测非常重要。建议为每个场景建立一组固定的测试问题集每次改动 Prompt 或模型后都跑一遍用回归结果判断是变好还是变差。没有评测优化就是盲人摸象。8.6 用 Wiki 方式沉淀 LLM 知识LLM 领域的发展速度远超大多数技术领域文档今天写了明天可能就过期。社区里有人建议用 Wiki 的方式整理 LLM 知识把模型、框架、工具、最佳实践分别建立条目持续更新。这种知识管理思路值得借鉴。你也可以建立自己的 LLM 知识库每跑通一个案例就把关键步骤和踩坑记录写进去。三个月后你会发现这份记录比任何收藏夹都更有价值。9. 总结与后续学习方向awesome-llm-apps 这个仓库的意义在于它把 LLM 应用从“概念”变成了“代码”。它让一个刚入门的开发者能在一个下午跑通自己的第一个 RAG 应用也让有经验的开发者在面对新方向时能快速找到可参考的案例结构。接下来你可以做三件事。第一选一个 RAG 案例把它完整跑通理解每一步在做什么。第二在此基础上尝试加入 Agent 能力让应用不仅能回答还能调用工具。第三关注 MCP 等工具接入标准这很可能会是未来一年 LLM 应用工程化最重要的方向之一。建议不要只是收藏而是真的去选一个案例把环境配起来跑通一个问答然后再改一改参数、换一换模型看看效果会发生什么变化。跑通一个比你收藏 100 个仓库都有用。