最近在梳理 LLM 应用开发的学习路径时发现很多新手容易陷入两个极端要么只看理论停留在“大模型能做什么”的层面要么一上来就啃 LangChain、LlamaIndex 源码被各种抽象概念绕晕。如果有一个项目能把常见的 LLM 应用场景集中展示还附带了可运行的代码学习效率会高很多。Shubhamsaboo 的awesome-llm-apps正是这样一个仓库。它不是一个“放满论文链接的收藏夹”而是一组能真正跑起来的 LLM 应用示例覆盖了 RAG、Agent、MCP、多工具调用等热门方向。本文会从项目结构、核心概念、环境配置、实战运行、常见报错和工程建议几个方面展开帮助你把它用起来。1. 背景与核心概念1.1 awesome-llm-apps 是什么awesome-llm-apps是一个在 GitHub 上持续维护的开源项目合集由开发者 Shubhamsaboo 创建。它收集了大量基于 LLMLarge Language Model大语言模型构建的应用程序示例每个示例都带有完整的代码、依赖文件和运行说明。和普通“awesome 列表”不同这个仓库里的项目不是单纯放一个 README 或论文链接而是实打实的 Python 项目。你可以直接克隆到本地配置好 API Key 后运行起来看到真实的大模型应用效果。目前仓库里覆盖的场景包括基于 RAGRetrieval-Augmented Generation检索增强生成的知识库问答多 Agent 协作系统MCPModel Context Protocol模型上下文协议客户端应用金融数据分析助手PDF、网页内容问答个人 AI 助手Slack、Discord 等平台集成1.2 它解决什么问题在 LLM 应用开发中很多人会遇到这样的困境官方文档看了不少但不知道从哪个项目入手。知道 RAG 的大致原理但遇到“怎么切分文档”“用什么向量库”“怎么处理多轮对话”就卡住了。想做一个 Agent 应用结果被 ReAct、Function Calling、工具调用这些概念挡住。网上教程很多但代码版本混乱跑不起来。awesome-llm-apps的价值在于它给出了可以直接运行的最小示例。它不是框架文档也不是系统教学课程而是一个“项目脚手架仓库”。你可以把它当作参考实现也可以基于它改造自己的业务应用。1.3 常见应用场景根据仓库中的项目可以归纳出几类典型应用场景场景说明对应项目方向企业知识库问答把内部文档、PDF、网页内容作为知识来源回答用户问题PDF RAG、Web 内容问答个人助理管理日程、发邮件、搜索网页信息Personal AI Assistant数据分析通过自然语言查询金融数据、分析股票趋势Finance Agent多 Agent 协作多个角色化的 Agent 分工完成任务Multi-Agent System平台集成在 Slack、Discord 中接入智能聊天机器人Slack AI AssistantMCP 应用开发构建支持外部工具和资源接入的 LLM 客户端MCP Client2. 环境准备与版本说明在运行awesome-llm-apps中的项目之前需要先把环境准备好。由于仓库中的项目以 Python 为主下面以 Python 环境为例说明。2.1 基础环境要求建议环境如下版本需要根据你的项目实际情况调整操作系统Windows 10/11、macOS 或主流 Linux 发行版均可。Python 版本3.9 及以上。部分项目可能要求 3.10 或 3.11建议安装 3.10 或 3.11 作为默认版本。包管理器pip 或 poetry。仓库部分项目使用requirements.txt部分使用pyproject.toml。Git用于克隆仓库。API Key根据项目不同可能需要 OpenAI API Key、Anthropic API Key、Tavily API Key、Pinecone API Key 等。向量数据库部分 RAG 项目需要 Chroma、Pinecone、Weaviate 等向量数据库。其中 Chroma 可以本地运行适合入门。2.2 克隆仓库git clone https://github.com/Shubhamsaboo/awesome-llm-apps.git cd awesome-llm-apps仓库目录较大如果你只想运行某一个项目也可以使用--depth 1参数进行浅克隆减少下载体积。2.3 创建虚拟环境强烈建议为每个项目创建独立的虚拟环境避免依赖冲突python -m venv venv source venv/bin/activate # Linux / macOS venv\Scripts\activate # Windows激活虚拟环境后再安装项目依赖。以chat_with_your_pdf这类项目为例cd chat_with_your_pdf pip install -r requirements.txt不同项目的依赖差异很大有的使用 LangChain有的使用 LlamaIndex有的使用 CrewAI建议按每个项目目录下的说明逐个安装。2.4 环境变量配置API Key 不要硬编码在代码中建议通过环境变量或.env文件管理。在项目根目录创建.env文件OPENAI_API_KEYsk-xxxxxxxxxxxxxxxx TAVILY_API_KEYtvly-xxxxxxxxxxxxxxxx PINECONE_API_KEYxxxxxxxxxxxxxxxx然后在代码中加载from dotenv import load_dotenv load_dotenv() import os openai_api_key os.getenv(OPENAI_API_KEY)这种方式的好处是代码提交到 GitHub 时不会泄露密钥也方便在不同环境中切换配置。3. 核心架构与原理拆解awesome-llm-apps中的项目看起来五花八门但拆开来看核心架构有不少共性。理解这些共性比跑通某一个项目更重要。3.1 典型 LLM 应用架构一个完整 LLM 应用通常包含以下模块用户交互层即前端界面仓库中常用 Streamlit、Gradio 或 FastAPI 实现负责收集用户输入并展示结果。应用逻辑层负责调度 LLM、管理对话状态、调用外部工具这是核心代码所在。外部工具层包括搜索 API、数据库、向量存储、邮件服务等扩展 LLM 的能力边界。LLM 层通过 API 调用 GPT、Claude、Llama 等模型接收 prompt 并返回结果。3.2 RAG 应用的工作流程RAGRetrieval-Augmented Generation检索增强生成是awesome-llm-apps中出现频率最高的模式之一。流程可以简化为加载文档读取 PDF、网页或其他格式的文档。文本切分把长文档切分成固定大小的 chunk避免超出模型上下文限制。向量化用 Embedding 模型把每个 chunk 转换成向量。存储把向量写入向量数据库。检索用户提问时把问题向量化在向量数据库中查找最相似的 chunk。生成把检索到的上下文和用户问题一起发给 LLM生成回答。对应到项目代码中通常会拆成两个阶段索引阶段和查询阶段。索引阶段只需要在文档变化时重新执行查询阶段每次用户提问都会触发。3.3 Agent 与工具调用Agent智能体是另一种常见模式。在 RAG 中LLM 主要做“阅读并回答”的工作而在 Agent 模式中LLM 变成了一个“决策者”它根据用户的需求决定调用哪个工具、按什么顺序调用。例如在金融分析 Agent 中LLM 可能会判断用户需要查询股票数据于是调用get_stock_price工具。拿到价格数据后调用get_company_news工具获取相关新闻。最后结合两组数据生成综合分析报告。这种能力依赖 Function Calling 或 Tool Calling 机制。OpenAI、Anthropic 等都提供了对应的 APILangChain、CrewAI 等框架则在更高层次上封装了调用逻辑。3.4 MCP 与外部工具连接近期热议的 MCPModel Context Protocol模型上下文协议也在仓库中有对应示例。MCP 可以理解为 LLM 和外部工具之间的“USB 接口”标准。它定义了工具、资源和提示词的统一协议格式开发者只需要实现 MCP Server任何支持 MCP 的 LLM 客户端都可以直接使用这些工具。MCP 之所以重要是因为它改变了工具集成的方式。在没有 MCP 之前每接入一个工具都要为 LLM 写一套专门的工具调用代码有了 MCP 之后工具提供方只需编写并托管一个 MCP Server所有兼容 MCP 的客户端都能直接调用。3.5 为什么需要 LLM 编排框架很多初学者会问直接调用 OpenAI API 不是很简单吗为什么还要用 LangChain、LlamaIndex、CrewAI 这些框架原因在于真实业务场景远比“发送一个请求”复杂需要管理多轮对话历史。需要对接多种向量数据库。需要封装重试、超时、错误处理。需要支持流式输出。需要在不同模型之间切换。需要编排多个 Agent 的协作流程。编排框架的价值在于把这些通用能力抽象成现成的模块让开发者专注于业务逻辑。不过也需要注意框架的抽象会隐藏底层细节出现问题时不熟悉原理反而更难排查。因此建议先通过原生 API 做一个简单 Demo再引入框架。4. 完整实战案例运行一个 RAG 问答应用下面选择仓库中一个比较经典的项目——PDF 问答聊天机器人来演示完整的运行流程。4.1 项目功能这个应用允许用户上传一个 PDF 文件然后针对 PDF 内容进行多轮提问。实现方式是读取 PDF 并切分成文本块。使用 OpenAI Embedding API 生成向量。将向量存入本地向量库本项目使用 Chroma。用户提问时检索相关文本块并调用 GPT 生成回答。4.2 创建项目结构在awesome-llm-apps仓库中找到对应项目目录。不同版本的项目结构略有差异通常包含以下文件chat_with_your_pdf/ ├── app.py ├── requirements.txt ├── .env ├── README.md └── utils.py4.3 添加依赖查看requirements.txt核心依赖通常包括streamlit openai langchain langchain-community chromadb pypdf python-dotenv tiktoken安装依赖pip install -r requirements.txt如果你是 Apple Silicon Mac安装chromadb时如果遇到编译问题可以尝试pip install chromadb --no-cache-dir4.4 编写核心代码下面的代码是一个简化版本的 PDF RAG 应用用于演示核心逻辑。为了便于理解我不使用完整框架而是保留关键链路。# 文件路径chat_with_your_pdf/simple_pdf_rag.py import os from dotenv import load_dotenv from pypdf import PdfReader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_openai import OpenAIEmbeddings, ChatOpenAI from langchain_community.vectorstores import Chroma from langchain.chains import RetrievalQA load_dotenv() # 1. 读取 PDF def load_pdf_text(pdf_path: str) - str: reader PdfReader(pdf_path) texts [] for page in reader.pages: text page.extract_text() if text: texts.append(text) return \n.join(texts) # 2. 切分文本 def split_text(text: str): splitter RecursiveCharacterTextSplitter( chunk_size1000, chunk_overlap200, separators[\n\n, \n, 。, , , ., !, ?, , ] ) return splitter.split_text(text) # 3. 构建向量库 def build_vectorstore(chunks): embeddings OpenAIEmbeddings(modeltext-embedding-3-small) vectorstore Chroma.from_texts( textschunks, embeddingembeddings, persist_directory./chroma_db ) return vectorstore # 4. 创建问答链 def create_qa_chain(vectorstore): llm ChatOpenAI(modelgpt-4o-mini, temperature0.2) qa_chain RetrievalQA.from_chain_type( llmllm, chain_typestuff, retrievervectorstore.as_retriever(search_kwargs{k: 4}) ) return qa_chain if __name__ __main__: pdf_path sample.pdf text load_pdf_text(pdf_path) chunks split_text(text) print(fPDF loaded, total {len(chunks)} chunks) vectorstore build_vectorstore(chunks) qa_chain create_qa_chain(vectorstore) while True: query input(请输入问题输入 exit 退出) if query.lower() in (exit, quit): break result qa_chain.invoke(query) print(回答:, result[result])4.5 运行与验证运行脚本python simple_pdf_rag.py预期输出PDF loaded, total 18 chunks 请输入问题输入 exit 退出输入一个与 PDF 内容相关的问题后程序会检索相关文本块并返回模型生成的回答。需要说明的是使用RetrievalQA时会有一个隐藏问题当文本块较多时stuff方式会把所有检索结果一次性塞进提示词中。如果检索到的文本块超过上下文长度就会报错。解决方式有两种减少k值例如从 4 改为 2。换用map_reduce或refine方式处理长文本。4.6 转换为 Web 应用如果你希望把脚本变成 Web 应用可以使用 Streamlit。核心改动是把控制台交互改为 Streamlit 的组件交互# 文件路径chat_with_your_pdf/streamlit_app.py import streamlit as st from simple_pdf_rag import load_pdf_text, split_text, build_vectorstore, create_qa_chain st.set_page_config(page_titlePDF RAG Chatbot, page_icon) st.title( 与你的 PDF 对话) uploaded_file st.file_uploader(上传 PDF 文件, typepdf) if uploaded_file is not None: with open(temp.pdf, wb) as f: f.write(uploaded_file.getbuffer()) text load_pdf_text(temp.pdf) chunks split_text(text) vectorstore build_vectorstore(chunks) qa_chain create_qa_chain(vectorstore) st.success(fPDF 加载完成共 {len(chunks)} 个文本块) if messages not in st.session_state: st.session_state.messages [] for message in st.session_state.messages: with st.chat_message(message[role]): st.markdown(message[content]) if prompt : st.chat_input(请输入问题): st.session_state.messages.append({role: user, content: prompt}) with st.chat_message(user): st.markdown(prompt) with st.chat_message(assistant): result qa_chain.invoke(prompt) st.markdown(result[result]) st.session_state.messages.append({role: assistant, content: result[result]})运行 Streamlit 应用streamlit run streamlit_app.py5. 常见问题与排查思路运行awesome-llm-apps中的项目时常见的报错和问题可以归纳为以下几类。问题现象常见原因解决思路提示ModuleNotFoundError: No module named langchain依赖未安装或安装在错误环境中确认当前虚拟环境已激活执行pip install -r requirements.txt提示AuthenticationError或Invalid API KeyAPI Key 错误或环境变量未加载检查.env文件是否位于当前目录确认.env中变量名与代码中一致提示ContextWindowExceededError检索到的文本块超过模型上下文限制减小chunk_size、减少k值或换用map_reduce方式向量库持久化失败目录权限或 Chroma 版本问题确保persist_directory对应目录可写升级或固定 chromadb 版本中文回答质量差文本切分时把中文句子切断在分隔符中加入中文标点或在完整代码中使用RecursiveCharacterTextSplitter并添加中文分隔符运行 Streamlit 后页面空白浏览器缓存或依赖冲突刷新页面检查终端是否有报错确认 openai 与 langchain-openai 版本兼容安装 chromadb 时编译报错Python 版本或系统依赖问题使用 Python 3.10 或 3.11尝试安装预编译版本或更新 pip除了表中内容还有一个经常被忽略的问题Embedding 模型和 Chat 模型不一致。在 RAG 流程中索引阶段的 Embedding 模型和查询阶段的 Embedding 模型必须是同一个否则向量空间不一致检索结果会非常差。如果你在运行时更换了 Embedding 模型需要删除旧的向量库并重新建立索引。排查问题时建议按照以下顺序进行检查环境变量是否加载成功在代码中打印os.getenv(OPENAI_API_KEY)确认不是None。检查当前使用的是不是正确的 Python 环境which python或where python。检查依赖版本是否冲突使用pip list查看已安装版本对照项目requirements.txt中是否有版本要求。检查网络连接如果使用httpx或requests访问外部 API确认所在网络能否正常访问对应服务。查看完整堆栈信息不要只看最后一行报错往上翻几行定位到具体代码位置。6. 最佳实践与工程建议6.1 目录与命名规范awesome-llm-apps中项目很多如果你要基于它扩展自己的项目建议遵循以下规范每个应用一个独立目录目录名用短横线分隔的小写单词例如chat-with-your-pdf。每个目录内包含README.md、requirements.txt、.env.example、源码文件和测试文件。在README.md中说明项目用途、运行步骤、环境变量清单和常见问题。.env.example很重要它列出了项目需要的全部环境变量但不包含真实密钥。提交到 Git 仓库时确保.env被.gitignore忽略。6.2 配置管理LLM 应用的配置项通常包括API Key 和 Base URL模型名称和版本Temperature 等生成参数向量数据库连接信息文本切分参数chunk_size、chunk_overlap检索参数k 值不要把这些配置散落在代码中。推荐使用 Pydantic Settings 或python-dotenv统一管理from pydantic_settings import BaseSettings class Settings(BaseSettings): openai_api_key: str openai_base_url: str https://api.openai.com/v1 model_name: str gpt-4o-mini embedding_model: str text-embedding-3-small chunk_size: int 1000 chunk_overlap: int 200 retrieval_k: int 4 class Config: env_file .env6.3 提示词设计与版本管理提示词Prompt是 LLM 应用效果的核心变量。工程化过程中建议把系统提示词和用户提示词分离。使用模板而不是字符串拼接。对提示词变更进行版本管理。建立测试集每次修改提示词后回归验证。例如from langchain_core.prompts import ChatPromptTemplate prompt ChatPromptTemplate.from_messages([ (system, 你是一个严谨的技术助手。请基于给定的上下文回答问题。如果上下文中没有相关信息请明确回答“根据提供的信息无法回答”。), (human, 上下文\n{context}\n\n问题{question}) ])这个提示词强调了“无法回答时要承认”能显著减少大模型的幻觉问题。6.4 异常处理与日志LLM API 调用可能因为网络波动、限流、超时而失败。生产环境必须做好重试和降级处理import time from openai import OpenAI client OpenAI() def call_llm_with_retry(prompt, max_retries3, delay2): for attempt in range(max_retries): try: response client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: prompt}] ) return response.choices[0].message.content except Exception as e: if attempt max_retries - 1: raise e time.sleep(delay * (attempt 1))日志方面至少需要记录每次 LLM 调用的耗时。使用的模型名称和 token 数量。错误类型和重试次数。用户输入的摘要注意隐私避免记录完整内容。6.5 性能优化RAG 应用的性能瓶颈通常在检索和生成两个环节。可以考虑以下几点使用缓存减少重复 LLM 调用。相同问题的结果可以存入 Redis 或数据库中。使用流式输出改善用户体验。对向量数据库建立索引优化检索速度。引入重排Rerank模型提升检索精度。对于超长文档先做摘要再做检索。6.6 生产环境注意事项如果你要把awesome-llm-apps中的原型改造成生产系统有几个关键差异需要重视安全边界对外提供 API 时要控制用户输入的注入风险。例如在提示词中要求模型忽略试图覆盖指令的内容同时在后端限制用户的 token 数量和调用频率。敏感信息保护确保日志中不出现 API Key、用户隐私等敏感内容。成本控制LLM API 按 token 计费需要监控每个用户或每个会话的 token 消耗。模型版本固定生产环境应固定模型版本或使用明确的模型别名防止模型供应商更新导致行为变化。数据隔离多租户场景下要确保每个用户只能访问自己的知识库数据。6.7 从 awesome-llm-apps 中学习的方法对于学习型读者建议不要只是“把项目跑起来”就结束。可以按照以下步骤深入读代码找到app.py或main.py中调用 LLM 的地方理解输入输出。改参数调整chunk_size、temperature、k等参数观察效果变化。换模型把 OpenAI 模型换成其他兼容接口的模型修改 Base URL 和模型名。加功能在现有项目上增加一个工具调用或换一个向量数据库。重写尝试不依赖框架用原生 API 实现一个最小 RAG。7. 总结与学习路线awesome-llm-apps是一个非常适合 LLM 应用开发入门和进阶的参考仓库。通过运行其中的项目你可以直观地理解 RAG、Agent、MCP 等核心概念的实际应用方式同时也为业务开发提供了可复用的脚手架。如果你刚开始接触 LLM 应用开发可以按照以下路径学习基础阶段运行一个最简单的对话应用理解 API 调用、token、temperature 等基础概念。RAG 阶段从 PDF 问答项目入手掌握文档切分、向量检索、上下文组装等核心技术。Agent 阶段学习函数调用尝试构建一个能调用搜索、计算等工具的小型 Agent。工程化阶段引入编排框架关注配置管理、异常处理、日志和性能优化。MCP 阶段了解模型上下文协议尝试编写一个 MCP Server 并接入客户端。在实际项目中最重要的不是“跑通 Demo”而是理解每个环节的原理和边界。跑通只是起点把项目改造成符合业务需求、能承受真实流量、具备可维护性的系统才是真正的挑战。如果文章对你有帮助可以收藏备用。也欢迎在评论区交流你在运行这些项目时遇到的问题一起完善这份 LLM 应用开发笔记。 awesome-llm-apps实战：从RAG到Agent的开源LLM应用项目全解析
最近在梳理 LLM 应用开发的学习路径时发现很多新手容易陷入两个极端要么只看理论停留在“大模型能做什么”的层面要么一上来就啃 LangChain、LlamaIndex 源码被各种抽象概念绕晕。如果有一个项目能把常见的 LLM 应用场景集中展示还附带了可运行的代码学习效率会高很多。Shubhamsaboo 的awesome-llm-apps正是这样一个仓库。它不是一个“放满论文链接的收藏夹”而是一组能真正跑起来的 LLM 应用示例覆盖了 RAG、Agent、MCP、多工具调用等热门方向。本文会从项目结构、核心概念、环境配置、实战运行、常见报错和工程建议几个方面展开帮助你把它用起来。1. 背景与核心概念1.1 awesome-llm-apps 是什么awesome-llm-apps是一个在 GitHub 上持续维护的开源项目合集由开发者 Shubhamsaboo 创建。它收集了大量基于 LLMLarge Language Model大语言模型构建的应用程序示例每个示例都带有完整的代码、依赖文件和运行说明。和普通“awesome 列表”不同这个仓库里的项目不是单纯放一个 README 或论文链接而是实打实的 Python 项目。你可以直接克隆到本地配置好 API Key 后运行起来看到真实的大模型应用效果。目前仓库里覆盖的场景包括基于 RAGRetrieval-Augmented Generation检索增强生成的知识库问答多 Agent 协作系统MCPModel Context Protocol模型上下文协议客户端应用金融数据分析助手PDF、网页内容问答个人 AI 助手Slack、Discord 等平台集成1.2 它解决什么问题在 LLM 应用开发中很多人会遇到这样的困境官方文档看了不少但不知道从哪个项目入手。知道 RAG 的大致原理但遇到“怎么切分文档”“用什么向量库”“怎么处理多轮对话”就卡住了。想做一个 Agent 应用结果被 ReAct、Function Calling、工具调用这些概念挡住。网上教程很多但代码版本混乱跑不起来。awesome-llm-apps的价值在于它给出了可以直接运行的最小示例。它不是框架文档也不是系统教学课程而是一个“项目脚手架仓库”。你可以把它当作参考实现也可以基于它改造自己的业务应用。1.3 常见应用场景根据仓库中的项目可以归纳出几类典型应用场景场景说明对应项目方向企业知识库问答把内部文档、PDF、网页内容作为知识来源回答用户问题PDF RAG、Web 内容问答个人助理管理日程、发邮件、搜索网页信息Personal AI Assistant数据分析通过自然语言查询金融数据、分析股票趋势Finance Agent多 Agent 协作多个角色化的 Agent 分工完成任务Multi-Agent System平台集成在 Slack、Discord 中接入智能聊天机器人Slack AI AssistantMCP 应用开发构建支持外部工具和资源接入的 LLM 客户端MCP Client2. 环境准备与版本说明在运行awesome-llm-apps中的项目之前需要先把环境准备好。由于仓库中的项目以 Python 为主下面以 Python 环境为例说明。2.1 基础环境要求建议环境如下版本需要根据你的项目实际情况调整操作系统Windows 10/11、macOS 或主流 Linux 发行版均可。Python 版本3.9 及以上。部分项目可能要求 3.10 或 3.11建议安装 3.10 或 3.11 作为默认版本。包管理器pip 或 poetry。仓库部分项目使用requirements.txt部分使用pyproject.toml。Git用于克隆仓库。API Key根据项目不同可能需要 OpenAI API Key、Anthropic API Key、Tavily API Key、Pinecone API Key 等。向量数据库部分 RAG 项目需要 Chroma、Pinecone、Weaviate 等向量数据库。其中 Chroma 可以本地运行适合入门。2.2 克隆仓库git clone https://github.com/Shubhamsaboo/awesome-llm-apps.git cd awesome-llm-apps仓库目录较大如果你只想运行某一个项目也可以使用--depth 1参数进行浅克隆减少下载体积。2.3 创建虚拟环境强烈建议为每个项目创建独立的虚拟环境避免依赖冲突python -m venv venv source venv/bin/activate # Linux / macOS venv\Scripts\activate # Windows激活虚拟环境后再安装项目依赖。以chat_with_your_pdf这类项目为例cd chat_with_your_pdf pip install -r requirements.txt不同项目的依赖差异很大有的使用 LangChain有的使用 LlamaIndex有的使用 CrewAI建议按每个项目目录下的说明逐个安装。2.4 环境变量配置API Key 不要硬编码在代码中建议通过环境变量或.env文件管理。在项目根目录创建.env文件OPENAI_API_KEYsk-xxxxxxxxxxxxxxxx TAVILY_API_KEYtvly-xxxxxxxxxxxxxxxx PINECONE_API_KEYxxxxxxxxxxxxxxxx然后在代码中加载from dotenv import load_dotenv load_dotenv() import os openai_api_key os.getenv(OPENAI_API_KEY)这种方式的好处是代码提交到 GitHub 时不会泄露密钥也方便在不同环境中切换配置。3. 核心架构与原理拆解awesome-llm-apps中的项目看起来五花八门但拆开来看核心架构有不少共性。理解这些共性比跑通某一个项目更重要。3.1 典型 LLM 应用架构一个完整 LLM 应用通常包含以下模块用户交互层即前端界面仓库中常用 Streamlit、Gradio 或 FastAPI 实现负责收集用户输入并展示结果。应用逻辑层负责调度 LLM、管理对话状态、调用外部工具这是核心代码所在。外部工具层包括搜索 API、数据库、向量存储、邮件服务等扩展 LLM 的能力边界。LLM 层通过 API 调用 GPT、Claude、Llama 等模型接收 prompt 并返回结果。3.2 RAG 应用的工作流程RAGRetrieval-Augmented Generation检索增强生成是awesome-llm-apps中出现频率最高的模式之一。流程可以简化为加载文档读取 PDF、网页或其他格式的文档。文本切分把长文档切分成固定大小的 chunk避免超出模型上下文限制。向量化用 Embedding 模型把每个 chunk 转换成向量。存储把向量写入向量数据库。检索用户提问时把问题向量化在向量数据库中查找最相似的 chunk。生成把检索到的上下文和用户问题一起发给 LLM生成回答。对应到项目代码中通常会拆成两个阶段索引阶段和查询阶段。索引阶段只需要在文档变化时重新执行查询阶段每次用户提问都会触发。3.3 Agent 与工具调用Agent智能体是另一种常见模式。在 RAG 中LLM 主要做“阅读并回答”的工作而在 Agent 模式中LLM 变成了一个“决策者”它根据用户的需求决定调用哪个工具、按什么顺序调用。例如在金融分析 Agent 中LLM 可能会判断用户需要查询股票数据于是调用get_stock_price工具。拿到价格数据后调用get_company_news工具获取相关新闻。最后结合两组数据生成综合分析报告。这种能力依赖 Function Calling 或 Tool Calling 机制。OpenAI、Anthropic 等都提供了对应的 APILangChain、CrewAI 等框架则在更高层次上封装了调用逻辑。3.4 MCP 与外部工具连接近期热议的 MCPModel Context Protocol模型上下文协议也在仓库中有对应示例。MCP 可以理解为 LLM 和外部工具之间的“USB 接口”标准。它定义了工具、资源和提示词的统一协议格式开发者只需要实现 MCP Server任何支持 MCP 的 LLM 客户端都可以直接使用这些工具。MCP 之所以重要是因为它改变了工具集成的方式。在没有 MCP 之前每接入一个工具都要为 LLM 写一套专门的工具调用代码有了 MCP 之后工具提供方只需编写并托管一个 MCP Server所有兼容 MCP 的客户端都能直接调用。3.5 为什么需要 LLM 编排框架很多初学者会问直接调用 OpenAI API 不是很简单吗为什么还要用 LangChain、LlamaIndex、CrewAI 这些框架原因在于真实业务场景远比“发送一个请求”复杂需要管理多轮对话历史。需要对接多种向量数据库。需要封装重试、超时、错误处理。需要支持流式输出。需要在不同模型之间切换。需要编排多个 Agent 的协作流程。编排框架的价值在于把这些通用能力抽象成现成的模块让开发者专注于业务逻辑。不过也需要注意框架的抽象会隐藏底层细节出现问题时不熟悉原理反而更难排查。因此建议先通过原生 API 做一个简单 Demo再引入框架。4. 完整实战案例运行一个 RAG 问答应用下面选择仓库中一个比较经典的项目——PDF 问答聊天机器人来演示完整的运行流程。4.1 项目功能这个应用允许用户上传一个 PDF 文件然后针对 PDF 内容进行多轮提问。实现方式是读取 PDF 并切分成文本块。使用 OpenAI Embedding API 生成向量。将向量存入本地向量库本项目使用 Chroma。用户提问时检索相关文本块并调用 GPT 生成回答。4.2 创建项目结构在awesome-llm-apps仓库中找到对应项目目录。不同版本的项目结构略有差异通常包含以下文件chat_with_your_pdf/ ├── app.py ├── requirements.txt ├── .env ├── README.md └── utils.py4.3 添加依赖查看requirements.txt核心依赖通常包括streamlit openai langchain langchain-community chromadb pypdf python-dotenv tiktoken安装依赖pip install -r requirements.txt如果你是 Apple Silicon Mac安装chromadb时如果遇到编译问题可以尝试pip install chromadb --no-cache-dir4.4 编写核心代码下面的代码是一个简化版本的 PDF RAG 应用用于演示核心逻辑。为了便于理解我不使用完整框架而是保留关键链路。# 文件路径chat_with_your_pdf/simple_pdf_rag.py import os from dotenv import load_dotenv from pypdf import PdfReader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_openai import OpenAIEmbeddings, ChatOpenAI from langchain_community.vectorstores import Chroma from langchain.chains import RetrievalQA load_dotenv() # 1. 读取 PDF def load_pdf_text(pdf_path: str) - str: reader PdfReader(pdf_path) texts [] for page in reader.pages: text page.extract_text() if text: texts.append(text) return \n.join(texts) # 2. 切分文本 def split_text(text: str): splitter RecursiveCharacterTextSplitter( chunk_size1000, chunk_overlap200, separators[\n\n, \n, 。, , , ., !, ?, , ] ) return splitter.split_text(text) # 3. 构建向量库 def build_vectorstore(chunks): embeddings OpenAIEmbeddings(modeltext-embedding-3-small) vectorstore Chroma.from_texts( textschunks, embeddingembeddings, persist_directory./chroma_db ) return vectorstore # 4. 创建问答链 def create_qa_chain(vectorstore): llm ChatOpenAI(modelgpt-4o-mini, temperature0.2) qa_chain RetrievalQA.from_chain_type( llmllm, chain_typestuff, retrievervectorstore.as_retriever(search_kwargs{k: 4}) ) return qa_chain if __name__ __main__: pdf_path sample.pdf text load_pdf_text(pdf_path) chunks split_text(text) print(fPDF loaded, total {len(chunks)} chunks) vectorstore build_vectorstore(chunks) qa_chain create_qa_chain(vectorstore) while True: query input(请输入问题输入 exit 退出) if query.lower() in (exit, quit): break result qa_chain.invoke(query) print(回答:, result[result])4.5 运行与验证运行脚本python simple_pdf_rag.py预期输出PDF loaded, total 18 chunks 请输入问题输入 exit 退出输入一个与 PDF 内容相关的问题后程序会检索相关文本块并返回模型生成的回答。需要说明的是使用RetrievalQA时会有一个隐藏问题当文本块较多时stuff方式会把所有检索结果一次性塞进提示词中。如果检索到的文本块超过上下文长度就会报错。解决方式有两种减少k值例如从 4 改为 2。换用map_reduce或refine方式处理长文本。4.6 转换为 Web 应用如果你希望把脚本变成 Web 应用可以使用 Streamlit。核心改动是把控制台交互改为 Streamlit 的组件交互# 文件路径chat_with_your_pdf/streamlit_app.py import streamlit as st from simple_pdf_rag import load_pdf_text, split_text, build_vectorstore, create_qa_chain st.set_page_config(page_titlePDF RAG Chatbot, page_icon) st.title( 与你的 PDF 对话) uploaded_file st.file_uploader(上传 PDF 文件, typepdf) if uploaded_file is not None: with open(temp.pdf, wb) as f: f.write(uploaded_file.getbuffer()) text load_pdf_text(temp.pdf) chunks split_text(text) vectorstore build_vectorstore(chunks) qa_chain create_qa_chain(vectorstore) st.success(fPDF 加载完成共 {len(chunks)} 个文本块) if messages not in st.session_state: st.session_state.messages [] for message in st.session_state.messages: with st.chat_message(message[role]): st.markdown(message[content]) if prompt : st.chat_input(请输入问题): st.session_state.messages.append({role: user, content: prompt}) with st.chat_message(user): st.markdown(prompt) with st.chat_message(assistant): result qa_chain.invoke(prompt) st.markdown(result[result]) st.session_state.messages.append({role: assistant, content: result[result]})运行 Streamlit 应用streamlit run streamlit_app.py5. 常见问题与排查思路运行awesome-llm-apps中的项目时常见的报错和问题可以归纳为以下几类。问题现象常见原因解决思路提示ModuleNotFoundError: No module named langchain依赖未安装或安装在错误环境中确认当前虚拟环境已激活执行pip install -r requirements.txt提示AuthenticationError或Invalid API KeyAPI Key 错误或环境变量未加载检查.env文件是否位于当前目录确认.env中变量名与代码中一致提示ContextWindowExceededError检索到的文本块超过模型上下文限制减小chunk_size、减少k值或换用map_reduce方式向量库持久化失败目录权限或 Chroma 版本问题确保persist_directory对应目录可写升级或固定 chromadb 版本中文回答质量差文本切分时把中文句子切断在分隔符中加入中文标点或在完整代码中使用RecursiveCharacterTextSplitter并添加中文分隔符运行 Streamlit 后页面空白浏览器缓存或依赖冲突刷新页面检查终端是否有报错确认 openai 与 langchain-openai 版本兼容安装 chromadb 时编译报错Python 版本或系统依赖问题使用 Python 3.10 或 3.11尝试安装预编译版本或更新 pip除了表中内容还有一个经常被忽略的问题Embedding 模型和 Chat 模型不一致。在 RAG 流程中索引阶段的 Embedding 模型和查询阶段的 Embedding 模型必须是同一个否则向量空间不一致检索结果会非常差。如果你在运行时更换了 Embedding 模型需要删除旧的向量库并重新建立索引。排查问题时建议按照以下顺序进行检查环境变量是否加载成功在代码中打印os.getenv(OPENAI_API_KEY)确认不是None。检查当前使用的是不是正确的 Python 环境which python或where python。检查依赖版本是否冲突使用pip list查看已安装版本对照项目requirements.txt中是否有版本要求。检查网络连接如果使用httpx或requests访问外部 API确认所在网络能否正常访问对应服务。查看完整堆栈信息不要只看最后一行报错往上翻几行定位到具体代码位置。6. 最佳实践与工程建议6.1 目录与命名规范awesome-llm-apps中项目很多如果你要基于它扩展自己的项目建议遵循以下规范每个应用一个独立目录目录名用短横线分隔的小写单词例如chat-with-your-pdf。每个目录内包含README.md、requirements.txt、.env.example、源码文件和测试文件。在README.md中说明项目用途、运行步骤、环境变量清单和常见问题。.env.example很重要它列出了项目需要的全部环境变量但不包含真实密钥。提交到 Git 仓库时确保.env被.gitignore忽略。6.2 配置管理LLM 应用的配置项通常包括API Key 和 Base URL模型名称和版本Temperature 等生成参数向量数据库连接信息文本切分参数chunk_size、chunk_overlap检索参数k 值不要把这些配置散落在代码中。推荐使用 Pydantic Settings 或python-dotenv统一管理from pydantic_settings import BaseSettings class Settings(BaseSettings): openai_api_key: str openai_base_url: str https://api.openai.com/v1 model_name: str gpt-4o-mini embedding_model: str text-embedding-3-small chunk_size: int 1000 chunk_overlap: int 200 retrieval_k: int 4 class Config: env_file .env6.3 提示词设计与版本管理提示词Prompt是 LLM 应用效果的核心变量。工程化过程中建议把系统提示词和用户提示词分离。使用模板而不是字符串拼接。对提示词变更进行版本管理。建立测试集每次修改提示词后回归验证。例如from langchain_core.prompts import ChatPromptTemplate prompt ChatPromptTemplate.from_messages([ (system, 你是一个严谨的技术助手。请基于给定的上下文回答问题。如果上下文中没有相关信息请明确回答“根据提供的信息无法回答”。), (human, 上下文\n{context}\n\n问题{question}) ])这个提示词强调了“无法回答时要承认”能显著减少大模型的幻觉问题。6.4 异常处理与日志LLM API 调用可能因为网络波动、限流、超时而失败。生产环境必须做好重试和降级处理import time from openai import OpenAI client OpenAI() def call_llm_with_retry(prompt, max_retries3, delay2): for attempt in range(max_retries): try: response client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: prompt}] ) return response.choices[0].message.content except Exception as e: if attempt max_retries - 1: raise e time.sleep(delay * (attempt 1))日志方面至少需要记录每次 LLM 调用的耗时。使用的模型名称和 token 数量。错误类型和重试次数。用户输入的摘要注意隐私避免记录完整内容。6.5 性能优化RAG 应用的性能瓶颈通常在检索和生成两个环节。可以考虑以下几点使用缓存减少重复 LLM 调用。相同问题的结果可以存入 Redis 或数据库中。使用流式输出改善用户体验。对向量数据库建立索引优化检索速度。引入重排Rerank模型提升检索精度。对于超长文档先做摘要再做检索。6.6 生产环境注意事项如果你要把awesome-llm-apps中的原型改造成生产系统有几个关键差异需要重视安全边界对外提供 API 时要控制用户输入的注入风险。例如在提示词中要求模型忽略试图覆盖指令的内容同时在后端限制用户的 token 数量和调用频率。敏感信息保护确保日志中不出现 API Key、用户隐私等敏感内容。成本控制LLM API 按 token 计费需要监控每个用户或每个会话的 token 消耗。模型版本固定生产环境应固定模型版本或使用明确的模型别名防止模型供应商更新导致行为变化。数据隔离多租户场景下要确保每个用户只能访问自己的知识库数据。6.7 从 awesome-llm-apps 中学习的方法对于学习型读者建议不要只是“把项目跑起来”就结束。可以按照以下步骤深入读代码找到app.py或main.py中调用 LLM 的地方理解输入输出。改参数调整chunk_size、temperature、k等参数观察效果变化。换模型把 OpenAI 模型换成其他兼容接口的模型修改 Base URL 和模型名。加功能在现有项目上增加一个工具调用或换一个向量数据库。重写尝试不依赖框架用原生 API 实现一个最小 RAG。7. 总结与学习路线awesome-llm-apps是一个非常适合 LLM 应用开发入门和进阶的参考仓库。通过运行其中的项目你可以直观地理解 RAG、Agent、MCP 等核心概念的实际应用方式同时也为业务开发提供了可复用的脚手架。如果你刚开始接触 LLM 应用开发可以按照以下路径学习基础阶段运行一个最简单的对话应用理解 API 调用、token、temperature 等基础概念。RAG 阶段从 PDF 问答项目入手掌握文档切分、向量检索、上下文组装等核心技术。Agent 阶段学习函数调用尝试构建一个能调用搜索、计算等工具的小型 Agent。工程化阶段引入编排框架关注配置管理、异常处理、日志和性能优化。MCP 阶段了解模型上下文协议尝试编写一个 MCP Server 并接入客户端。在实际项目中最重要的不是“跑通 Demo”而是理解每个环节的原理和边界。跑通只是起点把项目改造成符合业务需求、能承受真实流量、具备可维护性的系统才是真正的挑战。如果文章对你有帮助可以收藏备用。也欢迎在评论区交流你在运行这些项目时遇到的问题一起完善这份 LLM 应用开发笔记。