最近接了好几个朋友的需求，都是同一件事：想把手里的文档、笔记、行业资料变成能对话的智能助手。市面上方案一大堆，但要么讲得太浅、要么堆术语，真正能零基础照着做完的人不多。这篇就把我从零搭建DeepSeek Agent和知识库的完整过程拆开讲，包括踩过的坑、选型的逻辑、所有能直接抄的配置和代码。

先说结论：用DeepSeek做底层模型，配合Dify这类编排工具，加上一套整理得干净的知识库，普通人完全可以在一个周末内搭出能干活、能问答、能检索资料的智能体。不需要买显卡，不需要精通Python，甚至不需要理解太多机器学习原理。你只需要弄懂几个核心概念，然后照着下面的路径走一遍就行了。

我会尽量避免讲虚的，每一步都告诉你为什么这么做、参数怎么定、报错怎么处理，争取让你少走我走过的弯路。

1. 这套方案到底是什么，你能拿来做什么

1.1 你到底能用它做什么

我见过很多人听完“Agent”和“知识库”这两个词就懵了，觉得是很高深的东西。其实把它们拆开看，用途非常具体：

• 知识库解决的是“大模型不知道你的事”。DeepSeek再强，它没看过你的工作总结、项目文档、行业报告、考试笔记。把资料喂进去之后，你问“去年的项目复盘里提到的主要风险有哪些”，它能从你的文档里找到答案并告诉你，而不是瞎编。
• Agent解决的是“大模型光说不练”。给它接上搜索、计算、查表、调用API这些工具后，你说“帮我查一下今天天气并整理成一句简短提醒”，它会自己去查然后给出结果，而不是只给你一段“你可以这样查”的废话。

两者合在一起，就是你自己的智能助理：既有你的个人/团队知识做支撑，又能主动去执行任务。常见的落地方案包括：企业内部知识库问答机器人、个人写作素材助手、代码库查阅工具、会议纪要整理与检索、Excel数据问答。我有个朋友用它做一个农业知识库，把种植手册、植保方案、农资价格表全部灌进去，农户直接问“现在这个季节辣椒苗期重点防什么病”，它就能基于资料回答。

1.2 为什么选DeepSeek来搭这套东西

市面上可选的模型很多，但我个人强烈推荐从DeepSeek入手，理由就三条：

• 价格便宜。API调用按token计费，DeepSeek的定价大概是主流闭源模型的几十分之一。个人折腾阶段，注册送的额度就够玩很久，不需要一上来就充值。
• 推理能力在线。DeepSeek在数学、逻辑、代码生成这些方面表现相当能打，做Agent调度和工具调用时，它“听懂指令、按步骤执行”的能力比很多小模型强太多。
• API兼容OpenAI格式。意味着你不需要重新学一套SDK，几乎所有支持OpenAI接口的工具和框架，只要改一下base_url和API Key，就能直接用DeepSeek。

后面所有步骤，我都会默认你用的是DeepSeek。如果你已经熟悉了这套流程，再换其他模型也是分分钟的事。

2. 把Agent和知识库的原理一次聊透

2.1 Agent：让大模型从“会聊天”变成“会干活”

很多教程一上来就让你抄代码，抄完也不知道自己在干什么。所以我先花一点时间讲Agent的工作方式，这样后面配置的时候你心里有底。

Agent的核心就是“大模型当大脑，工具当手脚”。经典的工作循环是这样的：你先抛给Agent一个问题，它先理解你的意图，然后拆解成一个个小步骤，接着决定调用哪个工具来完成每个步骤，拿到工具返回结果后，再决定下一步做什么，直到认为任务完成，最后把答案汇总给你。

这个循环在业界叫ReAct，全称是Reason + Act，就是推理和行动交替进行。你不需要背这个名词，但你要理解：Agent和普通聊天机器人最大的区别在于，它不是一个“一问一答”的死板程序，而是一个“目标驱动”的执行者。比如你告诉它“帮我把这份文档里的所有联系人提取出来做成表格”，它会先看看有没有文档读取工具，再想想是否需要表格生成工具，然后一步步做完。

所以搭建Agent的关键，不是教它“知识”，而是给它“能力”：给它定义好有哪些工具、每个工具是干什么的、参数是什么格式，然后让它自己去编排怎么用。

2.2 知识库与RAG：怎么让模型知道你手里的资料

知识库的底层技术叫RAG，全称是Retrieval-Augmented Generation，检索增强生成。这个名词可以拆成三步理解：

第一步叫“入库”。把你的PDF、Word、Excel、Markdown文档全都拆成一段一段的文本，然后每段用向量化模型转成一个数字向量，相当于给每段内容算出一个“指纹”，存进一个专门的数据库里。这个数据库叫向量数据库。

第二步叫“检索”。用户提问时，系统先把用户的问题也转成向量，然后去向量数据库里找跟这个问题“距离最近”的几段文本，捞出来。

第三步叫“生成”。把捞出来的这些文本，拼在用户问题前面，作为背景材料一起发给大模型。大模型看到这些资料后，再组织语言回答问题。

这就是为什么大模型“没看过你的资料”也能回答你的问题——其实不是它学会了你的资料，而是系统在每次回答前，临时去你的资料库里“查资料”递给它看。这个思路就像你把一叠文件摆在咨询顾问面前，让他翻了之后回答你，而不是要求他背下你所有的文件。

2.3 为什么两者要合在一起用

只用知识库不加Agent，就是一个问答机器人：能回答，但不能执行操作，不能去外部查东西。只用Agent不接知识库，就是让一个没做过你行业功课的聪明人去干活，很多需要内部资料才能判断的任务，它只能靠猜。所以实际项目中，大多数是把知识库当成Agent的一个“知识工具”接进去。Agent收到问题后，如果发现需要参考资料，就先去知识库里检索，再把检索结果结合对话上下文，给出更准确的回答。

这套组合也是我下面要演示的完整形态。

3. 第一步：DeepSeek API调用，拿到你的第一个对话

3.1 注册、创建Key、看文档

不管后面用Dify还是自己写代码，都得先去DeepSeek开放平台创建一个账号。注册流程没什么好说的，用手机号或者邮箱就能搞定。登录后进到“API Keys”页面，创建一个新的API Key，这个Key长的样子像是“sk-”开头的一串字符，复制下来保存好，关掉页面之后Key就不会再完整显示了。

创建Key的时候要注意一件事：它会让你设置“额度限制”，建议先设一个比较低的月额度，比如几块钱，防止调试过程中不小心跑出大量token导致账单异常。我见过有人一边挂服务一边调测试，半天刷掉几十块钱的情况，设置限额是个好习惯。

然后就是看官方文档。DeepSeek的接口文档地址很好记，就是platform.deepseek.com里的文档页。你重点看两个接口即可：对话补全和模型列表。最重要的两个模型名要记住：deepseek-chat是通用对话模型，deepseek-reasoner是推理模型（会先给出推理过程再给答案）。做Agent和知识库问答，绝大多数场景用deepseek-chat就够，推理模型偶尔用在复杂拆解任务上。

3.2 用OpenAI SDK调DeepSeek，10行代码跑通

DeepSeek的API兼容OpenAI格式，所以你不需要装一个专门针对DeepSeek的库，直接装OpenAI的Python SDK就行，改一下base_url就好。

安装库：

pip install openai

然后写一个最简单的调用脚本：

from openai import OpenAI

client = OpenAI(
    api_key="sk-你的key",
    base_url="https://api.deepseek.com"
)

resp = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {"role": "system", "content": "你是一个简洁的助手。"},
        {"role": "user", "content": "你好，请用一句话介绍你自己。"}
    ],
    temperature=0.7,
    stream=False
)

print(resp.choices[0].message.content)

把api_key换成你自己的Key，运行一下，如果打印出了回答，说明你的API已经通了。这段代码看着简单，但后面很多工具接DeepSeek时其实都是在做类似的事：把工具或框架的“模型配置项”指向这个API地址和Key。

3.3 参数怎么调：temperature、top_p、max_tokens

很多新手拿到API就开始用，却从来不调参数，结果就是模型回答“太飘”或者“被截断”。这三个参数是使用频率最高的，我说一下我的经验：

temperature是温度，控制随机性，取值一般在0到1之间。做知识库问答和Agent任务，我建议设在0.1到0.3之间，尽量让模型“稳定输出”，不要自由发挥。如果是写文案、头脑风暴，可以调到0.8以上，让它更有创意。

top_p是核采样，作用和temperature类似，但机制不同。通常的做法是只调其中一个，保持另一个默认就好。我自己习惯把temperature设好，top_p保持默认不动。

max_tokens是最大输出长度。DeepSeek的上下文长度支持到64K，但“上下文”是输入和输出共用，你输出设的太大，留给输入的空间就小。做问答时我一般设成1000到2000，够用了；如果让Agent输出长报告，再调高。

这些参数在后面的Dify里都能通过界面调，先有概念，后面就不会手忙脚乱。

4. 工具选型：零基础该用哪套方案

4.1 零代码/低代码：Dify和Coze

如果你没有系统学过编程，我强烈建议不要一上来就碰LangChain，直接用一个可视化编排平台，你只需要拖拽配置就能完成Agent和知识库搭建。我自己最常用的是Dify，因为它开源免费，数据自己掌控，部署也不难，社区活跃，文档有中文版。它的核心功能正是知识库和Agent工作流，界面清晰，非常适合零基础起步。

另一个热门选项是扣子Coze，也是可视化搭建，集成了很多免配置的插件和知识库能力，而且和内容平台的联动做得很好。但它更偏云端使用，如果你想自己掌控数据、后期做二次开发，Dify会更合适。

4.2 写代码方案：LangChain和原生Function Calling

如果你有一点编程基础，或者以后想往Agent开发方向发展，那么除了可视化平台，你早晚要接触LangChain或者直接用原生的Function Calling方式。

LangChain是一套开发框架，封装好了许多模块，比如文档加载、文本切分、向量存储、Agent循环。好处是组件丰富、生态大，坏处是抽象层太多，出错后排查起来头大。我的建议是：想学框架，可以用LangChain做小项目练手；但真正上手业务时，原生Function Calling往往更可控。

原生Function Calling的意思是，你定义好JSON Schema格式的工具函数，DeepSeek返回的不是直接的回答，而是一个“是否调用某个工具、参数是什么”的结构化请求，然后你的代码来执行这个函数，再把结果回传给模型。这种方式看起来很基础，但反而更稳，因为它绕开了框架的复杂度。

4.3 面向日常工作的Agent工具：VSCode和Codex CLI

除了做一个在线的Agent应用，很多程序员关心的一个场景是“怎么让DeepSeek直接在编辑器里帮我写代码”。现在主流的做法就是在VSCode里装一个AI编程插件，比如Continue或者Cline，然后在插件设置里把模型服务地址指向DeepSeek的API。操作也不复杂，找到插件的配置文件，填上base_url为api.deepseek.com，模型名填deepseek-chat或deepseek-reasoner，再填上你的API Key，就能在编辑器里直接对话、改代码。

最近很火的Codex CLI同样可以接入DeepSeek。它本身是OpenAI出品的开源命令行编程代理，但你完全可以通过修改配置，让它指向DeepSeek的兼容接口。本质上，这类工具都是一个“Agent壳子”（业内叫harness），核心模型换成DeepSeek后，日常写代码完全够用，性价比还高。具体配置方法就是在config文件里把model_providers数组里替换成DeepSeek的base_url和api_key，模型名填deepseek-chat即可。

4.4 选型总结表

方案	适合人群	安装复杂度	灵活度	推荐指数
Dify	零基础/快速搭建	低（Docker一键）	中	推荐入门首选
Coze	需要大量现成插件	无（云端）	中	推荐快速尝鲜
LangChain	有Python基础	中	高	想学框架再用
原生Function Calling	有Python基础	中	高	推荐生产使用
VSCode插件/Codex CLI	程序员	低	中	推荐日常写代码

看完这个表你可能发现了，没有一套方案是万能的，你的选择取决于目的：想快速做出来，就用Dify；想深入Agent开发，就学原生方式；想纯提升写代码效率，就接编辑器插件。

5. 个人知识库搭建：从零开始构建可用语料

5.1 第一步是整理知识源，不是找工具

很多人做知识库的第一步是跑去部署软件，这是错的。知识库效果好不好，七成取决于你的源文件质量，三成取决于检索和生成。先花时间把知识源整理清楚，后面会省很多事。

我个人的习惯是用Obsidian来管理个人笔记。它能本地化存储，支持Markdown，文件夹结构自由，还有双链和标签体系。每次看到有价值的内容，我会按“领域/项目/主题”三层关系整理成笔记，顺手加标签。这样日积月累，就形成了一份结构清晰的知识库语料。后续要把内容喂给RAG系统时，这些Markdown文件直接就能用，不用做额外清洗。

如果你没有使用Obsidian的习惯，直接建一个文件夹，把文档按“类型+主题”命名放进去也行。关键是文件名要清晰，内容别是乱码或扫描件，能做到这步就已经超过70%的人了。

5.2 Word、PDF、Excel怎么解析进知识库

知识库平台支持的文件类型通常有：txt、markdown、pdf、docx、xlsx。但“支持”和“能解析好”完全是两回事，我一个个说：

• Word文档（docx）解析质量通常最好，Dify这类工具基本能做到按段落还原文字。
• PDF要分情况：文字版PDF解析效果还行，但扫描版PDF本质上是一张图片，必须先做OCR识别成文字才能用。Dify内置了Unstructured等解析组件，扫描件要额外配置OCR服务，建议直接用外部OCR工具先转成Markdown再导入。
• Excel不能直接当普通文本读。正确做法是先转成CSV或Markdown表格再导入，或者在知识库里把它定义成结构化数据集。直接塞一个格式复杂的Excel进去，切分时容易把表格内容切得稀碎，检索时基本是灾难。
• 网页链接可以抓取正文内容，但需要动态渲染的页面经常抓不全，最好还是手动复制成Markdown。

我踩过最大的坑就是PDF：有一批行业报告是扫描版，导入知识库后，检索出来的全是乱码。后来老老实实先用OCR工具跑了一遍，生成了文字版再导入，效果立刻就不一样了。

5.3 文本切分策略：决定检索质量的关键

这一步是很多人忽视但是最影响效果的环节。RAG系统不可能把一整本PDF当一个整体往模型里塞，它会按一定粒度把文本切成很多小块，这个动作叫切分。

Dify里的参数有两个：分段长度和分段重叠长度。分段长度表示每一块文本最多包含多少字符，我通常设为500到800个字符；分段重叠长度表示相邻两个分段之间重叠的部分，我习惯设为50到100个字符。重叠的意义是：如果某段关键信息正好落在两个分段交界处，没有重叠的话它会被硬生生拆开，检索时两边都不完整，答案就会残缺。

切分时还有几个细节要注意：不要在一个表格中间切分，Dify里可以把表格设置为“结构化格式”整体存储；尽量按标题层级切分，也就是先识别Markdown或Word里的标题，再在标题下切分，这样每个分段都有完整语义；代码块不要和其他正文混在一起切，否则引用起来很乱。

5.4 向量化和存储：Embedding模型与向量库怎么配

切分好的文本会进入向量化环节，生成向量后用向量数据库存储。向量化模型的选择也很关键，如果你用Dify的话，它默认支持OpenAI和多种本地模型。

如果你在云端用DeepSeek做生成模型，向量化模型可以选OpenAI的text-embedding-3-small，效果稳定，价格也很低。如果你不想用OpenAI，可以选开源的中文向量模型，比如bge-m3。bge-m3对中文的支持很好，而且可以通过Ollama本地跑，不用上传数据到第三方。

向量数据库这一层，Dify默认会用Weaviate或Qdrant之类的开源向量数据库，这些都内置了，基本不需要你操心。你只需要知道数据会以“向量+文本”的形式存起来，检索时按相似度排序召回即可。关于版本的话，Dify的Docker编排文件里已经写好了服务依赖，直接体验就好。

6. 用Dify完整搭建“知识库问答Agent”

6.1 Docker部署Dify并接入DeepSeek

Dify部署方式推荐用Docker Compose，一条命令就能启动整套服务。前提是你的电脑上装好了Docker和Docker Compose，没有的话先去装一下。

git clone https://github.com/langgenius/dify.git
cd dify/docker
cp .env.example .env
docker compose up -d

等服务启动起来后，浏览器打开http://localhost/install，设置管理员账号密码，完成初始化安装。

然后进到控制台，点击右上角头像进入“设置”，找到“模型供应商”，在“OpenAI-API-compatible”这一栏里添加自定义模型。这里要填几个关键信息：模型类型选“LLM”，模型名称填“deepseek-chat”，API Base URL填https://api.deepseek.com，API Key填你申请的Key。有些版本里还需要填“模型ID”，也是deepseek-chat。

配置完成后，在任意聊天窗口或应用里选择这个模型，就可以用DeepSeek生成内容了。

6.2 创建知识库并配置检索策略

进入“知识库”页面，点击“创建知识库”，给它起个名字，然后上传提前准备好的文档。上传后会进入分段和清洗的界面，这里你可以设置上一节说的分段长度和重叠长度。

知识库创建之后，还要设置“检索设置”。Dify提供了几种检索模式，我个人常用的组合是“向量检索+全文检索”的混合检索，配置一个权重比例，比如向量权重0.7、全文检索权重0.3。这样做的好处是：向量检索擅长找“意思相近但字面不同”的内容，全文检索擅长精确定位关键词，两者结合，召回效果比单用其中一种好很多。

另外建议打开“Rerank重排序”功能。召回阶段拿回来的候选分段可能很多，重排序模型会重新计算它们和问题的相关度，把真正有用的排到最前面。没有重排序的话，Top K只按向量距离截断，经常会混进几段无关内容。

6.3 搭建Agent应用：Prompt、工具与知识库串联

接下来进入核心环节。在Dify的“工作室”里，选择“创建空白应用”，类型选“Agent”。应用创建后，左侧是编排画布，右侧是预览界面。

先在“提示词”里写好角色设定。这里有个诀窍：提示词不要太笼统，要写清你的Agent是什么、能做什么、不能做什么、遇到不知道的内容怎么处理。我常用的一个模板是：

你是我的知识库助手，你可以通过查询知识库获取资料来回答我的问题。
回答规则：
1. 如果知识库中有明确答案，请引用相关内容并说明来源。
2. 如果知识库中没有相关内容，请明确告诉用户“当前知识库中未找到相关信息”，不要编造。
3. 回答尽量简洁，控制在300字以内。
4. 如果用户的问题需要实时信息或外部数据，请尝试使用工具获取。

然后在“工具”里，添加知识库检索工具和想要的外部工具。Dify默认有一些工具，比如Wikipedia搜索、网页访问等。如果是企业场景，还可以通过OpenAPI schema接入内部系统做自定义工具。把知识库工具加进去之后，还要在工具配置里选择你刚才创建的知识库，设置Retrieval Mode和TopK，TopK通常设为3到5，意思是每次检索取最相关的3到5段内容。

模型选择里记得选deepseek-chat，temperature在0.3以内。

6.4 发布、测试、调试全流程

配置完，先在右侧预览窗口里测试几个问题。我习惯准备一个“测试清单”，包含三类问题：能从知识库找到答案的问题、知识库里没有答案的问题、需要调用工具才能回答的问题。目的是验证三条链路通不通：检索链路、生成链路、工具链路。

发布也没什么复杂操作，在Dify里点击“发布”后，会生成一个WebApp访问地址，你把这个链接发给同事或朋友，他们就能直接在浏览器里使用这个智能体。Dify也提供API接口，方便后面接小程序、飞书、钉钉这些外部系统。

调试时最常用的是看“日志”。Dify里有“操作日志”，能看到每一次回答时模型收到了什么输入、调用了哪些工具、知识库召回了哪些段落。排查问题基本都是从这里入手，而不是猜模型为什么这么答。

7. 实操中的坑与排查方法

7.1 知识库检索效果差，问题出在哪

这是被问得最多的问题，我总结五个最常见的坑：

• 文本没切好。闭环过短导致语义不完整，或者过长导致信息稀释，优先检查分段的完整性和重叠设置。
• 标题信息丢失。Dify在切分时会提取标题作为分段的前缀上下文，如果你的文档没有层级标题，分段之间就缺少关联，检索准确率会明显下降。
• 没有开重排序。召回列表里混入无关内容，会影响最终答案。
• 知识库文件质量不行。扫描PDF、乱码表格、无意义的对话记录，这些都会让你的检索效果非常差，先清洗源文件再入库。
• 检索TopK太小或太大。TopK太小，信息不够；TopK太大，无关段落干扰模型。我一般3到5之间，再配合重排序效果最好。

7.2 Agent不调工具、回答跑偏怎么排查

Agent偶尔会出现“用户问一个需要知识库的问题，它却凭自己经验乱答”的情况。排查逻辑是这样：

先看Prompt里有没有明确告诉它要优先查知识库。大模型默认会按自己的知识储备回答，不明确说就不太会主动查资料。其次检查工具描述是否清晰。在Function Calling体系里，工具只有一个名字是不够的，要在描述里写清楚“这个工具用来解决什么问题、什么时候该用”。最后看模型输出日志。如果模型根本没生成工具调用请求，说明它在决策环节就没想用工具；如果生成了，但参数报错，那是工具定义有问题。

另外，temperature太高也容易让模型“跑偏”，Agent场景一定把temperature控制在0.3以内。

7.3 API报错和限流处理

用DeepSeek时最常见的报错是429，意思是请求太频繁，超过了接口限流。解决方案也简单：加一个重试机制，或者在请求之间增加一点间隔。用OpenAI SDK时，它本身就支持重试参数，可以设置max_retries。

另一个常见错误是401，API Key错误或未生效，检查Key是否有粘贴空格、是否用了错误的Key。

还有400类错误，多半是请求参数格式有问题，比如max_tokens超出了模型上限、messages格式不对、system提示词里有非法字符。用官方SDK一般不会犯这种错，但如果用自定义HTTP请求时要仔细检查JSON结构。

7.4 本地部署DeepSeek到底划不划算

最后聊一下很多人会问的本地部署问题。为什么要本地部署？主要是数据隐私和长期成本。但本地部署大模型需要显卡，deepseek-r1的量化版7B模型大概需要6GB显存，14B模型约10GB显存，32B模型要20GB以上显存。如果你没有独立显卡或只有核显，体验会非常差。

部署方式上，最简单是用Ollama，一条命令就能把模型跑起来，然后你把Dify里的模型配置指向本地的Ollama接口即可。同时向量化模型也可以本地化，比如Ollama上跑bge-m3。

我的观点是：如果你是个人学习或体验，直接用官方API最省心；如果数据敏感，必须内网处理，那就在一台有显卡的机器上用Ollama本地部署，同时把知识库和向量化也全部内网化。计划要现实一点：模型参数越小，效果相对越弱，不要让本地7B模型去做复杂的检索和推理任务，否则你会觉得这套方案不行，其实只是模型选小了。

8. 我的几点实践经验

整套做完之后，我最大的体会是：DeepSeek的强大，不只是模型本身，而是它和开源生态的兼容性。因为API完全兼容OpenAI格式，你可以很自然地在Dify、VSCode、Codex CLI、甚至很多开源框架里换用DeepSeek。这种“随时可替换”的能力，给了普通开发者很大的选择空间，不为某一个平台绑死。

再分享一个我日常使用的小技巧：不要把知识库当成一个“灌进去就能用”的仓库，它是一个需要持续维护的东西。每隔一段时间，我会清理失效的旧文档、合并重复主题、重新分段和向量化。就像整理房间一样，定期整理的知识库，检索效果会越来越好。

最后说一句：任何AI项目，工具只是门槛，真正决定上限的还是你对问题的拆解能力，以及你对数据的组织能力。起手别贪大，从一个200篇文档的知识库开始，做一个小而准确的助手，等你跑通整条链路之后，再往里面加Agent的复杂能力。