1. 从零到一这套Agent Skills课程到底在讲什么先把话说在前头这套东西不是那种“三天速成AI大师”的营销课。我花了半个月时间把市面上关于Agent Skills、大模型、LangChain、RAG的零散知识重新梳理了一遍砍掉了那些花里胡哨的噱头只留下真正能跑通、能落地、能写进简历里的硬核内容。如果你是一个完全没碰过大模型的小白或者写过几行Python但不知道怎么跟LLM打交道那这套东西就是给你准备的。核心目标很明确让你从“知道大模型是什么”到“能自己搭一个带知识库的智能体”中间不跳步、不省略、不拿“读者自行查阅资料”来糊弄人。整个学习路径分成三大块——基础认知、工具链实操、项目实战。基础认知解决“LLM、Token、Embedding、RAG这些词到底啥意思”的问题工具链实操带你跑通LangChain、Ollama、向量数据库的安装和调用项目实战则是把前面所有东西串起来做一个能回答你私有文档问题的Agent。适合谁学零基础转行者、在校学生想攒项目经验、产品经理需要理解技术边界、甚至是有经验的开发者想快速补齐Agent这块拼图。我不假设你会深度学习不假设你懂Transformer甚至不假设你数学有多好。但有一点要求你得愿意动手敲代码哪怕只是复制粘贴然后改参数。光看不动手看一百遍也学不会。提示这套内容基于2026年初的工具版本和社区实践整理大模型领域迭代极快遇到API变动或库版本冲突时优先查阅官方文档的迁移指南不要死磕旧教程。2. 基础认知LLM、Token、Embedding到底在说什么2.1 大模型不是“懂”语言它只是在做概率预测很多人第一次用ChatGPT或者Claude的时候会觉得“它真的理解我在说什么”。但如果你去翻一下LLM的底层原理会发现它本质上就是一个超级复杂的下一个Token预测器。你给它一段话它根据训练时见过的海量文本算出下一个最可能出现的词是什么然后把这个词拼上去再预测下一个如此循环。这里的关键概念是Token。Token不是字也不是词而是模型处理文本的最小单位。英文里一个Token大约对应0.75个单词中文里一个汉字通常对应1到2个Token。为什么你要关心Token因为API按Token收费上下文窗口按Token限制模型生成速度也按Token计算。我见过太多新手一上来就往上下文里塞几万字结果账单爆炸或者直接报错。那Embedding又是什么简单说就是把一段文本转换成一串数字向量。这串数字捕捉了文本的语义信息——意思相近的文本它们的向量在空间里的距离就近。举个例子“猫”和“猫咪”的向量距离很近“猫”和“汽车”的向量距离就很远。RAG之所以能工作全靠Embedding这个能力把你的问题转成向量去向量数据库里找最相似的文档片段再把找到的内容塞给LLM让它组织答案。注意Embedding模型和生成模型是两码事。生成模型负责“说话”Embedding模型负责“找资料”。你可以用OpenAI的text-embedding-3-small做Embedding用GPT-4o做生成也可以全用开源方案比如用BGE-M3做Embedding用Qwen2.5做生成。选型逻辑后面会细讲。2.2 RAG不是万能药但没有RAG的Agent基本是废的RAG全称Retrieval-Augmented Generation检索增强生成。这个名字听起来很学术但拆开看就三件事检索、增强、生成。用户问一个问题系统先去知识库里检索相关内容把检索结果作为额外上下文“增强”给LLMLLM再基于这些上下文“生成”最终回答。为什么需要RAG因为LLM有两个致命缺陷。第一它的知识有截止日期训练数据之后发生的事情它不知道。第二它不知道你私有的东西比如你公司的内部文档、你个人的笔记、某个小众产品的说明书。RAG就是给LLM外挂了一个“开卷考试”的能力让它能实时查阅资料再答题。但RAG不是银弹。我踩过最大的坑就是以为把文档切一切、塞进向量库、检索出来就完事了。实际上检索质量决定了整个系统的上限。如果检索出来的内容跟问题不相关LLM再强也只能胡编乱造。所以后面我会花很大篇幅讲文档切分策略、Embedding模型选型、检索结果重排序这些细节。2.3 Agent Skills的核心让模型学会“用工具”Agent这个词现在被滥用了好像什么都能叫Agent。但在我这套课程的定义里Agent是一个能自主决定调用什么工具、按什么顺序调用、根据调用结果决定下一步动作的系统。它跟普通LLM调用的区别在于普通调用是你问一句它答一句Agent是你给它一个目标它自己规划步骤去完成。Agent Skills就是Agent能调用的那些工具。比如搜索工具让Agent能查实时信息计算工具让Agent能精确算数而不是靠概率猜代码执行工具让Agent能跑Python脚本处理数据RAG检索工具让Agent能查私有知识库API调用工具让Agent能操作外部系统LangChain和LangGraph就是帮你把这些工具串起来的框架。LangChain提供了标准化的工具接口和链式调用能力LangGraph则更进一步让你能用图结构定义Agent的状态流转和条件分支。我个人的经验是简单场景用LangChain的AgentExecutor就够了复杂场景比如多轮工具调用、人工审核介入、循环重试必须上LangGraph。3. 工具链选型别被“最新最强”带偏了3.1 本地部署还是API调用先算一笔账新手最纠结的问题之一我到底该用OpenAI/Claude的API还是本地跑Ollama我的建议是分阶段来。学习阶段优先用API。原因很简单省时间。本地部署一个7B模型下载加配置至少半小时跑起来可能还各种报错。API调用五分钟就能跑通第一个Demo先把信心建立起来。而且API的效果通常比同参数量的本地模型好因为人家是经过大量工程优化的。生产阶段看数据敏感性和成本。如果数据绝对不能出内网那必须本地部署。如果数据不敏感且调用量不大API的按量付费反而更划算。我算过一笔账用GPT-4o-mini处理100万Token大约几块钱而本地部署一张RTX 4090加上电费和维护成本跑同样的量至少贵三到五倍。混合方案这是我最推荐的。用本地小模型做Embedding和初步筛选用API大模型做最终生成。这样既保护了数据隐私原始文档不出本地又保证了回答质量。提示Ollama是目前本地部署最省心的工具一条命令就能拉取和运行模型。但注意Ollama默认的上下文长度可能不够需要在Modelfile里手动调大num_ctx参数否则长文档会被截断。3.2 LangChain还是LangGraph别为了用而用LangChain的定位是“LLM应用开发框架”提供了大量现成的组件文档加载器、文本分割器、向量存储接口、各种Agent类型。它的优势是生态丰富你想要的几乎都有现成实现。劣势是抽象层太厚出问题的时候调试很痛苦而且版本迭代快网上的教程经常对不上号。LangGraph的定位是“有状态的Agent编排框架”。它把Agent的执行过程建模成一张图节点是操作边是流转条件。优势是控制力强你能精确控制每一步的状态和分支。劣势是学习曲线陡需要理解状态机、检查点、中断恢复这些概念。我的建议先用LangChain把基础RAG跑通再上LangGraph做复杂Agent。不要一上来就啃LangGraph很容易被劝退。等你理解了Chain、Tool、Memory这些基础概念之后再看LangGraph会觉得顺理成章。3.3 向量数据库怎么选别上来就Milvus向量数据库的选择取决于你的数据规模和部署环境。我列一个实际用过的对比方案适用场景优点缺点FAISS本地实验、小规模零依赖、速度快不支持增删改、无持久化Chroma快速原型、中小规模安装简单、API友好大规模性能一般Qdrant生产环境、中等规模过滤功能强、Rust性能好需要单独部署Milvus大规模、分布式扩展性强、功能全运维复杂、资源占用高pgvector已有PostgreSQL不用额外组件性能不如专用向量库我的经验是个人项目用Chroma就够了公司内部工具用Qdrant只有数据量上千万级别才需要考虑Milvus。很多教程一上来就教Milvus结果新手光装环境就卡三天完全没必要。4. 实操过程从零搭一个能查私有文档的Agent4.1 环境准备与依赖安装先把基础环境搭好。我假设你用的是Windows或者MacLinux用户应该不需要我教。# 创建虚拟环境别问为什么问就是避免依赖冲突 python -m venv agent-env source agent-env/bin/activate # Windows用 agent-env\Scripts\activate # 安装核心依赖 pip install langchain langchain-community langchain-openai pip install chromadb sentence-transformers pip install streamlit # 用来做简单界面这里解释一下每个包的作用。langchain是核心框架langchain-community包含社区贡献的各种集成langchain-openai是OpenAI的官方集成。chromadb是向量数据库sentence-transformers用来跑本地的Embedding模型。streamlit是快速做Web界面的工具比Flask简单一百倍。注意LangChain的版本更新非常频繁不同版本之间的API可能完全不兼容。建议在requirements.txt里锁定版本号比如langchain0.3.0否则今天跑通的代码明天可能就报错。4.2 文档加载与切分这一步决定了RAG的上限很多人随便找个文本分割器设个chunk_size1000就完事了。我告诉你这是RAG效果差的最大元凶。文档切分的核心矛盾是切得太碎语义不完整切得太大检索不精准。我的经验值是中文文档chunk_size500到800overlap100到150英文文档chunk_size1000到1500overlap200代码文档按函数或类切分不要按固定长度但光看长度还不够。好的切分策略应该尽量保持语义单元的完整性。比如按段落切、按标题切、按句子边界切。LangChain提供了RecursiveCharacterTextSplitter它会优先按段落分段落太长再按句子分句子太长再按字符分。这个递归策略比固定长度切分好得多。from langchain.text_splitter import RecursiveCharacterTextSplitter splitter RecursiveCharacterTextSplitter( chunk_size600, chunk_overlap120, separators[\n\n, \n, 。, , , , , , ], length_functionlen, )注意separators的顺序中文标点要放在英文标点前面否则中文句子会被错误切分。这个细节很多教程都不讲但实际影响很大。4.3 Embedding模型选型别盲目追求“最强”Embedding模型的选择直接决定了检索质量。我实测过几个主流方案模型维度中文效果速度部署难度text-embedding-3-small1536好快API调用BGE-M31024很好中等本地部署text2vec-large-chinese1024好中等本地部署m3e-base768中等快本地部署我的推荐如果数据不敏感直接用OpenAI的text-embedding-3-small省心且效果好。如果必须本地用BGE-M3它是目前中文开源Embedding里综合表现最好的。但有一个坑要注意Embedding模型换了必须重新索引所有文档。因为不同模型生成的向量空间不一样混用会导致检索结果完全错乱。我见过有人换了模型但没重建索引然后抱怨RAG效果差排查了半天才发现是这个问题。4.4 检索策略优化从“能搜到”到“搜得准”基础RAG的检索就是拿问题向量去数据库里找最相似的Top-K个片段。但这样做的命中率往往不够。我常用的优化手段有三个第一查询改写。用户的问题往往很口语化直接拿去检索效果不好。可以先用LLM把问题改写成更适合检索的形式。比如用户问“那个新功能怎么用来着”改写成“XX新功能的使用方法”。第二混合检索。向量检索擅长语义匹配但对关键词精确匹配不敏感。可以同时做BM25关键词检索然后把两路结果融合。LangChain的EnsembleRetriever就支持这个。第三重排序。先检索出Top-20个候选再用一个重排序模型比如BGE-Reranker对这20个结果精排取Top-5送给LLM。这一步能显著提升准确率代价是增加一点延迟。from langchain.retrievers import EnsembleRetriever, ContextualCompressionRetriever from langchain.retrievers.document_compressors import CrossEncoderReranker from langchain_community.cross_encoders import HuggingFaceCrossEncoder # 混合检索 ensemble_retriever EnsembleRetriever( retrievers[vector_retriever, bm25_retriever], weights[0.7, 0.3] ) # 重排序 model HuggingFaceCrossEncoder(model_nameBAAI/bge-reranker-v2-m3) compressor CrossEncoderReranker(modelmodel, top_n5) final_retriever ContextualCompressionRetriever( base_compressorcompressor, base_retrieverensemble_retriever )这套组合拳下来检索命中率能从60%左右提升到85%以上。代价是每次查询多花几百毫秒但完全值得。4.5 Agent组装把工具串起来现在到了最核心的部分把检索器包装成Tool让Agent能自主调用。from langchain.tools.retriever import create_retriever_tool from langchain.agents import AgentExecutor, create_openai_tools_agent from langchain_openai import ChatOpenAI from langchain import hub # 把检索器包装成工具 retriever_tool create_retriever_tool( final_retriever, nameknowledge_base_search, description搜索私有知识库。当用户询问文档相关的问题时使用此工具。 ) # 可以再加一个计算工具 from langchain_community.tools import WikipediaQueryRun from langchain_community.utilities import WikipediaAPIWrapper tools [retriever_tool] # 创建Agent llm ChatOpenAI(modelgpt-4o-mini, temperature0) prompt hub.pull(hwchase17/openai-tools-agent) agent create_openai_tools_agent(llm, tools, prompt) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue) # 跑起来 result agent_executor.invoke({input: 我们公司的报销流程是什么}) print(result[output])这里的关键是description字段。Agent靠这个描述来决定什么时候调用这个工具。描述写得越清楚Agent的判断越准确。我见过有人写“搜索工具”四个字就完事了然后抱怨Agent不调用。你把描述写成“当用户询问公司内部政策、流程、文档相关问题时使用此工具搜索私有知识库”效果完全不一样。5. 常见问题与排查技巧实录5.1 检索结果不相关怎么办这是RAG最高频的问题。排查顺序如下检查切分粒度。把检索到的片段打印出来看如果片段本身就不完整或者包含太多无关内容说明切分策略有问题。检查Embedding模型。用几个已知相关的问题测试看检索结果是否合理。如果完全不相关可能是模型选错了或者索引没重建。检查查询本身。用户的问题是否太模糊试试查询改写。增加重排序。如果Top-20里有相关结果但Top-5里没有重排序能解决。5.2 Agent不调用工具直接胡编答案这个问题通常有三个原因工具描述不清楚。Agent不知道什么时候该用这个工具。Prompt没有强调。在系统提示里明确写“如果问题涉及私有知识必须先调用knowledge_base_search工具”。模型能力不够。小模型对工具调用的判断能力弱换大一点的模型或者用专门优化过function calling的模型。5.3 本地模型跑起来特别慢先确认你是不是在用CPU跑。如果是那慢是正常的。7B模型在CPU上跑生成速度可能只有每秒几个Token。解决方案用GPU哪怕是消费级显卡用量化版本比如Q4_K_M速度能快两三倍效果损失很小换更小的模型比如Qwen2.5-3B日常问答够用了5.4 上下文长度不够长文档被截断Ollama默认的上下文长度通常是2048或4096对于RAG场景往往不够。需要在Modelfile里调大FROM qwen2.5:7b PARAMETER num_ctx 8192然后重新创建模型。注意调大上下文会增加显存占用8K上下文大概需要额外1-2GB显存。5.5 常见问题速查表问题现象可能原因解决方法检索结果完全不相关Embedding模型不匹配重建索引确保查询和索引用同一模型Agent不调用工具工具描述太模糊重写description明确使用场景回答包含幻觉检索内容不足增加Top-K加重排序Prompt强调“仅基于上下文回答”生成速度慢CPU推理或模型太大换GPU用量化模型换小模型内存溢出上下文太长或批量太大减小chunk_size降低batch_sizeAPI报错rate limit调用频率过高加指数退避重试或换用本地模型6. 进阶方向从“能用”到“好用”6.1 多模态RAG图片也能检索传统RAG只能处理文本但很多文档里有图表、截图、流程图。多模态RAG的思路是用多模态Embedding模型比如CLIP把图片也转成向量存到同一个向量空间里。检索的时候文本查询能同时召回相关文本和图片。目前这个方向还在快速演进开源方案里效果比较好的是用LLaVA或者Qwen-VL做图片描述生成把图片转成文字描述再走文本RAG。虽然损失了一些视觉信息但工程上简单可靠。6.2 Agent记忆让对话有连续性基础Agent是无状态的每次对话都是全新的。但实际场景里用户希望Agent记得之前说过什么。LangGraph提供了Checkpointer机制能把每轮对话的状态持久化到数据库里。下次对话时自动加载历史状态实现多轮记忆。from langgraph.checkpoint.sqlite import SqliteSaver memory SqliteSaver.from_conn_string(:memory:) graph builder.compile(checkpointermemory) # 调用时传入thread_id区分不同会话 config {configurable: {thread_id: user-123}} graph.invoke({messages: [(user, 我叫小明)]}, config) graph.invoke({messages: [(user, 我叫什么)]}, config) # 会记得6.3 评估与监控别凭感觉判断好坏RAG系统上线后怎么知道它回答得好不好靠人工看几个案例是不够的。需要建立评估体系检索命中率检索结果里有多少是真正相关的回答忠实度回答是否完全基于检索内容有没有胡编回答相关性回答是否切题可以用LLM as Judge的方式自动评估也可以用RAGAS这类专门工具。我个人的做法是每周抽100条真实用户查询人工标注加自动评估结合持续跟踪指标变化。7. 一些掏心窝子的经验这套东西我前后迭代了十几版踩过的坑比写过的代码还多。说几个我觉得最值得分享的第一不要追求一步到位。很多人一上来就想搭一个全能的Agent能查文档、能算数、能调API、能写代码。结果每个模块都半吊子整体效果稀烂。正确的做法是先跑通最简单的RAG确保检索和生成没问题再一个一个加工具。第二数据质量比模型重要。我见过太多人花大量时间调模型参数却不愿意花半小时把文档整理干净。PDF里的乱码、重复的页眉页脚、无关的广告内容这些都会严重干扰检索。把数据清洗做好效果提升比换模型明显得多。第三日志和可观测性是生命线。Agent出问题的时候如果没有详细的日志你根本不知道是哪一步错了。LangSmith或者LangFuse这类工具能记录每一次调用的输入输出排查问题效率提升十倍。第四别忽视成本。API调用看起来便宜但量大了很吓人。我见过一个项目每天跑几万次查询一个月账单几千美元。优化手段包括缓存常见问题的回答、用小模型做初步筛选、限制单次查询的Token数。第五保持学习但别焦虑。大模型领域每天都有新东西今天出个新框架明天出个新模型。你不可能什么都学。抓住核心概念——Embedding、检索、生成、工具调用——这些底层逻辑不会变。新工具只是换了个壳理解了本质就能快速上手。最后分享一个我常用的调试技巧把Agent的思考过程打印出来。LangChain的AgentExecutor有个verbose参数设为True之后能看到Agent每一步的决策。当你发现Agent的行为不符合预期时看它的思考过程往往能立刻定位问题。这个习惯帮我省了无数个小时的排查时间。