2026/8/31 8:22:19
FEATURED · 精选文章 
还有不到一个月柏林GTC就要开幕了。按惯例我这种每天跟大模型和Agent打交道的开发者会把关注的议题分成两类一类是GPU和基础设施另一类是模型、框架和应用。今年的情况有些特别——身边同事聊得最凶的不再是某张卡有多少TFlops而是两个词智能体Agent和开源模型。这个变化不是偶然。过去两年大家默认一个判断闭源模型能力最强想做出好产品就直接调API。但到了2025年越来越多团队发现真正难的不是让模型“会说话”而是让模型能在一个真实业务系统里“干活”。而一旦要干活开源自部署模型、可改代码的Agent框架一下子就从小众玩具变成了生产环境里的必选项。这篇文章不打算复述GTC的参会指南也不是新闻稿而是想聊清楚一件事为什么“智能体开源模型”会成为当前AI工程化的主线以及如果你现在就想亲手跑通一个最小智能体应该怎么做。读完你会得到一套能直接上手的环境搭建路径、示例代码和排错清单。1. 智能体为什么把开源模型推上了主场过去一年模型层的竞争主线是参数和评测分数。但在真正的业务场景里模型只是智能体的大脑而智能体要稳定工作依赖的是可控性、可观测性和可定制性。这三个词恰好在开源模型上有明显优势。先说可控性。闭源API无论多强你都无法查看它在工具调用中的完整决策逻辑。一旦Agent出现“该调用工具时不调不该调时瞎调”的问题你只能改Prompt碰运气。开源模型则是本地文件你可以直接改采样参数、换解码策略甚至用工具调用的日志反推是哪一层出错。再说可观测性。Agent系统的失败点非常多意图识别错、检索结果不相关、工具返回解析失败、上下文被截断。闭源API只能看到一份日志而自部署的开源模型可以完整打印从输入到输出的每个阶段这对排错是实质性帮助。最后是可定制性。真实业务里的工具调用格式五花八门企业内部API、数据库查询、审批流、低代码平台。开源模型社区通常能更快适配新工具协议配合微调、LoRA、Q-LoRA等手段你甚至可以把模型训练成某个垂直领域的“专用Agent大脑”。当然闭源模型在综合能力和稳定性上仍然领先。但智能体场景对“正确执行工具调用”的要求比“生成一段漂亮文案”更高而开源模型在这条赛道上的进步速度肉眼可见。许多开发者选择开源模型不是情怀而是工程上的理性选择。2. 基础概念智能体、开源模型和框架的关系为了避免后面的实操看得一头雾水这里先把几个核心概念讲清楚。智能体Agent在工程上的定义可以理解成一个循环接收任务 → 大模型规划 → 调用工具获取信息 → 根据结果继续决策 → 直到完成任务。它区别于普通聊天机器人的地方在于它拥有“行动能力”可以通过工具影响到外部系统。开源模型指的是权重公开、允许自由下载和部署的模型例如 Llama、Qwen、DeepSeek 系列。它们的价值不仅是省API费用更重要的是可以放在自己的服务器上数据不出门推理过程完全透明。智能体框架是帮你把“模型 工具 记忆 工作流”串起来的脚手架。常见的有三种形态代码框架如 LangChain、LlamaIndex适合程序员自己编排复杂逻辑。可视化平台如 Dify、Coze适合快速搭建企业级应用Dify 可以本地部署Coze 主要托管在云端。轻量Agent工具如 AutoGPT、Claude Code 这类面向特定任务的编程助手。很多人在概念上容易混淆另外两个东西工作流Workflow和 RAG。工作流是提前画好的固定路线用户触发一个节点流程就按顺序走中间不改变流向。Agent 则不同它会在每一步根据当前状态决定“下一步调用哪个工具”。所以如果你的业务逻辑是确定性的优先用工作流只有当决策路径足够复杂且动态变化时才值得引入 Agent。RAG检索增强生成是给模型外挂知识库先检索相关文档再让模型基于检索结果生成答案。它可以看作是 Agent 的一种“记忆模块”但 Agent 的能力边界更宽它还可以调用搜索、写数据库、发消息等工具。简单做一张对比表概念核心特点典型使用场景工作流固定步骤人工编排客服咨询流程、定时任务Agent动态决策自主调用工具智能运维、数据分析助手RAG从外部知识库检索再回答企业知识库问答多Agent多个智能体分工协作复杂项目拆解、多角色模拟真实项目中这些概念经常叠加。例如一个企业级智能体内部先有一个工作流做意图识别命中知识问题就走 RAG命中操作类请求就走工具调用如果路径太复杂再由 Agent 动态决策。开源模型在这个叠加结构里所处的层级是统一的“推理引擎”。3. 环境准备与前置条件在你本地或者一台 Linux 服务器上跑通智能体 demo需要准备这样一套环境。3.1 硬件与系统如果只做功能验证不用苛刻的显卡要求。Ollama 在 Mac M系列和 Linux/Windows 上都能跑CPU 也能运行只是速度较慢。建议至少 16GB 内存如果有 NVIDIA 显卡8GB 以上显存体验会好很多。生产环境再考虑 A100/H100 甚至多卡推理验证阶段完全不必。3.2 软件依赖Docker 与 Docker Compose用于部署 Dify 等平台。Python 3.10 以上用于写调用代码。Ollama 或 vLLM用于本地启动开源模型。vLLM 适合高并发生产Ollama 适合个人开发和验证。Git拉取 Dify 项目代码。3.3 模型选择验证阶段推荐选参数量 7B~8B 级别的开源模型例如 qwen2.5:7b 或 llama3.1:8b。它们既有不错的工具调用能力又不会让普通电脑跑不动。如果显存有限也可以选择 3B/4B 参数量的量化版本。版本说明各模型的版本号更新很快本文以 qwen2.5:7b 为例演示实际使用时建议以官方仓库最新版本为准。4. 核心流程拆解搭一个能查资料的智能体下面要搭建的 demo 目标很具体用户问一个问题智能体先判断是否需要搜索内部知识库如果需要就从已上传的文档中检索最后基于检索结果生成回答。整个过程要在本地完成。4.1 第一步启动开源模型服务模型是智能体的心脏。我们先用 Ollama 把开源模型跑起来它启动后默认监听11434端口并提供一个 OpenAI 兼容的接口。后面所有环节都可以通过这个接口访问模型这样万一想把模型换成别的改一个 URL 就行。# 启动 Ollama 服务 ollama serve # 拉取并运行一个 7B 模型 ollama pull qwen2.5:7b ollama run qwen2.5:7b 你好介绍一下你自己这里真正容易踩坑的地方是ollama serve 。在部分 Linux 环境下后台进程会因为终端退出而关闭更稳妥的方式是使用nohup ollama serve ollama.log 21 或者直接用 systemd 管理。4.2 第二步部署 Dify 平台Dify 是一个开源的LLM应用开发平台能可视化编排 Agent、知识库、工作流。我们用 Docker Compose 部署它这样不用手动配置数据库和 Redis。git clone https://github.com/langgenious/dify.git cd dify/docker cp .env.example .env docker compose up -d注意仓库地址以官方为准如果 clone 速度慢可以先下载 zip 包再解压。启动后访问http://localhost初始化管理员账号。首次启动需要拉取较多镜像时间取决于网络。如果中途失败先执行docker compose pull重试不要反复up -d。4.3 第三步在 Dify 中配置模型供应商登录 Dify 后进入“设置 → 模型供应商”选择 OpenAI-API-compatible 类型填写API Base URLhttp://host.docker.internal:11434/v1API Key任意非空字符串比如ollamaModels 列表添加qwen2.5:7b这里有个关键点Dify 本身跑在 Docker 容器里容器内访问宿主机的 Ollama 服务不能用localhost要用host.docker.internal。如果你把 Dify 直接装在宿主机上则可以填http://localhost:11434/v1。4.4 第四步创建聊天助手Agent应用在 Dify 中新建“聊天助手”应用选择已配置好的 qwen2.5:7b 模型。然后在“编排”页面打开 Agent 模式并添加工具例如“知识检索”。上传几篇技术文档到知识库设置好分段长度和检索模式。这一阶段不需要写代码但编排逻辑是整个 demo 的核心。要明确告诉模型先检索知识库再基于检索结果回答如果知识库没有答案要明确说“不知道”不能凭空编造。4.5 第五步测试并接入API在 Dify 右上角可以打开调试对话框直接输入问题测试。确认回答符合预期后再到“访问 API”页面创建 API Key。后面所有客户端都通过这个 Key 访问智能体能力。5. 完整示例与代码实现这一节给出三个可以直接运行的示例。第一个示例负责验证本地模型第二个示例演示如何用 Python 调用模型接口第三个示例展示通过 Dify API 与智能体交互。5.1 示例一用命令行验证本地模型模型服务启动后先用最简单的命令验证不要把问题直接抛到后面复杂的链路里。ollama pull qwen2.5:7b curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5:7b, messages: [{role: user, content: 请用一句话解释什么是智能体}], max_tokens: 128 }如果返回包含choices[0].message.content的 JSON说明模型服务正常。注意这里的接口路径是/v1/chat/completions这是 Ollama 兼容 OpenAI 协议的标准入口。5.2 示例二用 Python 调用开源模型写代码时尽量使用 OpenAI SDK因为本地模型的接口是兼容模式。这样以后切换到闭源API时代码改动量很小。# 文件路径agent_demo/model_client.py from openai import OpenAI client OpenAI( base_urlhttp://localhost:11434/v1, # 指向本地 Ollama 服务 api_keyollama # 本地服务不校验填任意非空值 ) def chat_with_model(prompt: str) - str: response client.chat.completions.create( modelqwen2.5:7b, messages[ { role: system, content: 你是一个严谨的技术助手回答要简洁不确定时明确说不知道。 }, { role: user, content: prompt } ], temperature0.2, max_tokens512 ) return response.choices[0].message.content if __name__ __main__: text chat_with_model(Agent 中的 tool calling 和普通函数调用有什么区别) print(text)运行前先安装依赖pip install openai python agent_demo/model_client.py这段代码展示了一个最小可用模式确定性任务用低温度创造性任务再调高温度。在 Agent 场景里尽量把temperature控制在 0.2 以下减少模型随机发挥导致工具调用失败的概率。5.3 示例三通过 Dify API 发布智能体服务Dify 应用配置完成后可以直接用 HTTP 接口将它变成可供业务系统调用的服务。假设你的 API Key 是app-xxxxx请求方式如下curl --location --request POST http://localhost/api/chat-messages \ --header Authorization: Bearer app-xxxxx \ --header Content-Type: application/json \ --data-raw { inputs: {}, query: 请查一下知识库里关于模型量化的说明并提炼出三个要点, response_mode: blocking, user: csdn-demo }response_mode可以填blocking或streaming。开发调试阶段推荐用blocking返回完整 JSON生产环境为了用户体验一般用streaming做流式输出。下面是一个简单的 Python 调用封装# 文件路径agent_demo/dify_client.py import requests DIFY_URL http://localhost/api/chat-messages API_KEY app-xxxxx def ask_agent(query: str, user_id: str csdn-demo) - dict: headers { Authorization: fBearer {API_KEY}, Content-Type: application/json } payload { inputs: {}, query: query, response_mode: blocking, user: user_id } response requests.post(DIFY_URL, headersheaders, jsonpayload, timeout120) response.raise_for_status() return response.json() if __name__ __main__: result ask_agent(什么是 Agent 的记忆模块) print(result[answer])这个示例是一个通用的接入范式。你可以把它嵌到飞书机器人、Web后端、命令行工具里让任何入口都具备智能体能力。6. 运行结果与效果验证完成上面的示例后需要从三个层面确认系统真的能工作。6.1 验证模型层执行示例二后正常输出的是一段结构清晰的中文回答。判断标准不是内容“好不好”而是进程没有报错返回文本非空。如果模型回答出现“API 连接错误”第一步先检查curl http://localhost:11434/api/tags是否能列出模型列表。6.2 验证知识检索层在 Dify 后台测试知识库问答时可以打开“日志”面板观察每次请求的检索链路。关键看两点是否检索到了相关文档片段模型是否引用了检索内容而不是自己编造。如果检索结果为空多半是文档分段不合理或者 Embedding 模型没有配置正确需要回到知识库做分段调整。6.3 验证 API 层通过curl调用 Dify 接口如果请求成功返回的 JSON 会包含answer、conversation_id、message_id字段。其中conversation_id很重要后续多轮对话需要把它原样传回否则智能体会丢失上下文。{ answer: 知识库中提到模型量化是将参数从高精度转换为低精度的过程..., conversation_id: abc123..., message_id: msg-001 }只要answer非空且HTTP 状态码为 200就说明整条链路已经打通客户端 → Dify → 本地开源模型 → 知识库检索 → 回复。7. 常见问题与排查思路我在不同项目里见过很多类似的问题这里列出一份高频问题清单问题现象可能原因排查方式解决方案连接 Ollama 失败Ollama 服务没启动或端口被占用curl http://localhost:11434/api/tags启动ollama serve查看端口占用容器内访问不到宿主机模型使用了localhost而不是host.docker.internal在容器内curl host.docker.internal:11434改用host.docker.internal并开放防火墙模型回答质量差模型太小或 Prompt 表达不清查看 Dify 日志中检索到的上下文换更大模型或优化 system promptAgent 不调用工具tool 描述太模糊或模型不支持复杂 tool calling在编排页面测试单个工具精简工具描述使用 tool 字段明确参数格式Dify 镜像拉取慢网络原因查看 Docker 拉取日志配置镜像加速执行docker compose pull显存不够导致 OOM模型参数量过大执行ollama ps查看显存占用换小模型或使用量化版如qwen2.5:3b一个容易被忽略的问题是本地 CPU 推理速度很慢容易触发 API 超时。如果 Dify 或客户端设置的超时时间太短模型还在生成时请求就被中断了。解决办法是把超时时间调大或者减少max_tokens。8. 最佳实践与工程建议跑通 demo 只是第一步。如果要把它变成生产系统下面这些建议值得参考。8.1 模型选型不要只盯评测分数评测分数高不等于在 Agent 场景里好用。优先选择社区反馈中“工具调用稳定”的模型并且用你真实的工具 Schema 去做回归测试。建议准备一组固定的测试用例每次换模型或升级版本后都跑一遍防止模型更新带来隐形行为变化。8.2 把模型层做成可替换的接口上面的示例中本地模型和 Dify 都兼容 OpenAI 协议。建议在项目里专门封装一层 model provider不要直接在业务代码中写死某个模型的 URL。这样一旦生产环境需要切换到更大的闭源模型或者自建 vLLM 集群只需要改配置不用改业务逻辑。8.3 工具调用要有权限边界Agent 可以调用外部工具这既是能力也是风险。生产环境要对每个工具做鉴权不能给 Agent 一把万能钥匙。例如让 Agent 连接数据库时应该使用只读账号调用企业 API 时要限制 IP 和请求频率。还要设计人工审批节点涉及高风险操作删除数据、转账、发布内容必须停下來等确认。8.4 建立可观测性和评估体系每个 Agent 请求都应该记录用户问题、模型决策链路、调用过的工具、工具返回结果、最终回复、耗时和 token 消耗。这些日志不仅能帮你定位问题也是未来优化 Prompt 和模型调优的数据基础。评估时不要只看单个回答好不好要构建一个包含几十到上百条真实场景的评测集每次改动都对比一次准确率。8.5 能用工作流就不要强行用 AgentAgent 很酷但成本高、不稳定。如果你的业务场景只有固定的3个分支用工作流十秒就能跑完而且结果可预期。只有决策路径复杂、需要模型反复判断的情况才值得引入 Agent。一个比较务实的方式是外层先用工作流做粗粒度路由路由到复杂场景后再触发 Agent 子流程。8.6 开源模型与闭源 API 混合使用开源模型和闭源 API 不是二选一。很多团队的做法是简单请求走本地小模型长尾复杂的请求走闭源大模型或者用开源模型做前置筛选把最高价值的请求提升给更贵的模型。这样既保住质量又能控制成本。9. 总结与后续学习方向这次柏林 GTC 大概率会有大量关于智能体、开源模型和硬件协同的讨论。但真正能让你在现场不焦虑的不是又多看了哪款新品而是你自己已经跑通过一条最小链路开源模型加载、本地知识库、工具调用、API 接入。这套链路并不复杂但它重新定义了 AI 应用开发的最小单位。过去你可能认为“大模型产品 一个 Prompt 一个 API”现在你更清楚智能体是一个由模型、工具、记忆、控制流组成的系统工程。开源模型让这个系统有了透明、可控、可定制的大脑而 GTC 这样的技术会议只是帮我们更快看到行业下一步的演进方向。如果你刚接触智能体建议先照着本文跑通 demo不要一开始就追求多 Agent 协作。先让一个 Agent 在一个业务场景里稳定工作再考虑复杂编排。可以继续关注的方向包括工具调用协议的标准化、长上下文管理、多 Agent 协同模式、以及基于开源模型的持续微调与评测体系。在踏上前往柏林的航班之前我会先把上面的最小 Demo 再跑一遍。技术会议的热度退得很快真正能留下的是自己亲手跑通的那套流程。
智能体+开源模型：本地搭建最小 Agent 应用实战指南
还有不到一个月柏林GTC就要开幕了。按惯例我这种每天跟大模型和Agent打交道的开发者会把关注的议题分成两类一类是GPU和基础设施另一类是模型、框架和应用。今年的情况有些特别——身边同事聊得最凶的不再是某张卡有多少TFlops而是两个词智能体Agent和开源模型。这个变化不是偶然。过去两年大家默认一个判断闭源模型能力最强想做出好产品就直接调API。但到了2025年越来越多团队发现真正难的不是让模型“会说话”而是让模型能在一个真实业务系统里“干活”。而一旦要干活开源自部署模型、可改代码的Agent框架一下子就从小众玩具变成了生产环境里的必选项。这篇文章不打算复述GTC的参会指南也不是新闻稿而是想聊清楚一件事为什么“智能体开源模型”会成为当前AI工程化的主线以及如果你现在就想亲手跑通一个最小智能体应该怎么做。读完你会得到一套能直接上手的环境搭建路径、示例代码和排错清单。1. 智能体为什么把开源模型推上了主场过去一年模型层的竞争主线是参数和评测分数。但在真正的业务场景里模型只是智能体的大脑而智能体要稳定工作依赖的是可控性、可观测性和可定制性。这三个词恰好在开源模型上有明显优势。先说可控性。闭源API无论多强你都无法查看它在工具调用中的完整决策逻辑。一旦Agent出现“该调用工具时不调不该调时瞎调”的问题你只能改Prompt碰运气。开源模型则是本地文件你可以直接改采样参数、换解码策略甚至用工具调用的日志反推是哪一层出错。再说可观测性。Agent系统的失败点非常多意图识别错、检索结果不相关、工具返回解析失败、上下文被截断。闭源API只能看到一份日志而自部署的开源模型可以完整打印从输入到输出的每个阶段这对排错是实质性帮助。最后是可定制性。真实业务里的工具调用格式五花八门企业内部API、数据库查询、审批流、低代码平台。开源模型社区通常能更快适配新工具协议配合微调、LoRA、Q-LoRA等手段你甚至可以把模型训练成某个垂直领域的“专用Agent大脑”。当然闭源模型在综合能力和稳定性上仍然领先。但智能体场景对“正确执行工具调用”的要求比“生成一段漂亮文案”更高而开源模型在这条赛道上的进步速度肉眼可见。许多开发者选择开源模型不是情怀而是工程上的理性选择。2. 基础概念智能体、开源模型和框架的关系为了避免后面的实操看得一头雾水这里先把几个核心概念讲清楚。智能体Agent在工程上的定义可以理解成一个循环接收任务 → 大模型规划 → 调用工具获取信息 → 根据结果继续决策 → 直到完成任务。它区别于普通聊天机器人的地方在于它拥有“行动能力”可以通过工具影响到外部系统。开源模型指的是权重公开、允许自由下载和部署的模型例如 Llama、Qwen、DeepSeek 系列。它们的价值不仅是省API费用更重要的是可以放在自己的服务器上数据不出门推理过程完全透明。智能体框架是帮你把“模型 工具 记忆 工作流”串起来的脚手架。常见的有三种形态代码框架如 LangChain、LlamaIndex适合程序员自己编排复杂逻辑。可视化平台如 Dify、Coze适合快速搭建企业级应用Dify 可以本地部署Coze 主要托管在云端。轻量Agent工具如 AutoGPT、Claude Code 这类面向特定任务的编程助手。很多人在概念上容易混淆另外两个东西工作流Workflow和 RAG。工作流是提前画好的固定路线用户触发一个节点流程就按顺序走中间不改变流向。Agent 则不同它会在每一步根据当前状态决定“下一步调用哪个工具”。所以如果你的业务逻辑是确定性的优先用工作流只有当决策路径足够复杂且动态变化时才值得引入 Agent。RAG检索增强生成是给模型外挂知识库先检索相关文档再让模型基于检索结果生成答案。它可以看作是 Agent 的一种“记忆模块”但 Agent 的能力边界更宽它还可以调用搜索、写数据库、发消息等工具。简单做一张对比表概念核心特点典型使用场景工作流固定步骤人工编排客服咨询流程、定时任务Agent动态决策自主调用工具智能运维、数据分析助手RAG从外部知识库检索再回答企业知识库问答多Agent多个智能体分工协作复杂项目拆解、多角色模拟真实项目中这些概念经常叠加。例如一个企业级智能体内部先有一个工作流做意图识别命中知识问题就走 RAG命中操作类请求就走工具调用如果路径太复杂再由 Agent 动态决策。开源模型在这个叠加结构里所处的层级是统一的“推理引擎”。3. 环境准备与前置条件在你本地或者一台 Linux 服务器上跑通智能体 demo需要准备这样一套环境。3.1 硬件与系统如果只做功能验证不用苛刻的显卡要求。Ollama 在 Mac M系列和 Linux/Windows 上都能跑CPU 也能运行只是速度较慢。建议至少 16GB 内存如果有 NVIDIA 显卡8GB 以上显存体验会好很多。生产环境再考虑 A100/H100 甚至多卡推理验证阶段完全不必。3.2 软件依赖Docker 与 Docker Compose用于部署 Dify 等平台。Python 3.10 以上用于写调用代码。Ollama 或 vLLM用于本地启动开源模型。vLLM 适合高并发生产Ollama 适合个人开发和验证。Git拉取 Dify 项目代码。3.3 模型选择验证阶段推荐选参数量 7B~8B 级别的开源模型例如 qwen2.5:7b 或 llama3.1:8b。它们既有不错的工具调用能力又不会让普通电脑跑不动。如果显存有限也可以选择 3B/4B 参数量的量化版本。版本说明各模型的版本号更新很快本文以 qwen2.5:7b 为例演示实际使用时建议以官方仓库最新版本为准。4. 核心流程拆解搭一个能查资料的智能体下面要搭建的 demo 目标很具体用户问一个问题智能体先判断是否需要搜索内部知识库如果需要就从已上传的文档中检索最后基于检索结果生成回答。整个过程要在本地完成。4.1 第一步启动开源模型服务模型是智能体的心脏。我们先用 Ollama 把开源模型跑起来它启动后默认监听11434端口并提供一个 OpenAI 兼容的接口。后面所有环节都可以通过这个接口访问模型这样万一想把模型换成别的改一个 URL 就行。# 启动 Ollama 服务 ollama serve # 拉取并运行一个 7B 模型 ollama pull qwen2.5:7b ollama run qwen2.5:7b 你好介绍一下你自己这里真正容易踩坑的地方是ollama serve 。在部分 Linux 环境下后台进程会因为终端退出而关闭更稳妥的方式是使用nohup ollama serve ollama.log 21 或者直接用 systemd 管理。4.2 第二步部署 Dify 平台Dify 是一个开源的LLM应用开发平台能可视化编排 Agent、知识库、工作流。我们用 Docker Compose 部署它这样不用手动配置数据库和 Redis。git clone https://github.com/langgenious/dify.git cd dify/docker cp .env.example .env docker compose up -d注意仓库地址以官方为准如果 clone 速度慢可以先下载 zip 包再解压。启动后访问http://localhost初始化管理员账号。首次启动需要拉取较多镜像时间取决于网络。如果中途失败先执行docker compose pull重试不要反复up -d。4.3 第三步在 Dify 中配置模型供应商登录 Dify 后进入“设置 → 模型供应商”选择 OpenAI-API-compatible 类型填写API Base URLhttp://host.docker.internal:11434/v1API Key任意非空字符串比如ollamaModels 列表添加qwen2.5:7b这里有个关键点Dify 本身跑在 Docker 容器里容器内访问宿主机的 Ollama 服务不能用localhost要用host.docker.internal。如果你把 Dify 直接装在宿主机上则可以填http://localhost:11434/v1。4.4 第四步创建聊天助手Agent应用在 Dify 中新建“聊天助手”应用选择已配置好的 qwen2.5:7b 模型。然后在“编排”页面打开 Agent 模式并添加工具例如“知识检索”。上传几篇技术文档到知识库设置好分段长度和检索模式。这一阶段不需要写代码但编排逻辑是整个 demo 的核心。要明确告诉模型先检索知识库再基于检索结果回答如果知识库没有答案要明确说“不知道”不能凭空编造。4.5 第五步测试并接入API在 Dify 右上角可以打开调试对话框直接输入问题测试。确认回答符合预期后再到“访问 API”页面创建 API Key。后面所有客户端都通过这个 Key 访问智能体能力。5. 完整示例与代码实现这一节给出三个可以直接运行的示例。第一个示例负责验证本地模型第二个示例演示如何用 Python 调用模型接口第三个示例展示通过 Dify API 与智能体交互。5.1 示例一用命令行验证本地模型模型服务启动后先用最简单的命令验证不要把问题直接抛到后面复杂的链路里。ollama pull qwen2.5:7b curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5:7b, messages: [{role: user, content: 请用一句话解释什么是智能体}], max_tokens: 128 }如果返回包含choices[0].message.content的 JSON说明模型服务正常。注意这里的接口路径是/v1/chat/completions这是 Ollama 兼容 OpenAI 协议的标准入口。5.2 示例二用 Python 调用开源模型写代码时尽量使用 OpenAI SDK因为本地模型的接口是兼容模式。这样以后切换到闭源API时代码改动量很小。# 文件路径agent_demo/model_client.py from openai import OpenAI client OpenAI( base_urlhttp://localhost:11434/v1, # 指向本地 Ollama 服务 api_keyollama # 本地服务不校验填任意非空值 ) def chat_with_model(prompt: str) - str: response client.chat.completions.create( modelqwen2.5:7b, messages[ { role: system, content: 你是一个严谨的技术助手回答要简洁不确定时明确说不知道。 }, { role: user, content: prompt } ], temperature0.2, max_tokens512 ) return response.choices[0].message.content if __name__ __main__: text chat_with_model(Agent 中的 tool calling 和普通函数调用有什么区别) print(text)运行前先安装依赖pip install openai python agent_demo/model_client.py这段代码展示了一个最小可用模式确定性任务用低温度创造性任务再调高温度。在 Agent 场景里尽量把temperature控制在 0.2 以下减少模型随机发挥导致工具调用失败的概率。5.3 示例三通过 Dify API 发布智能体服务Dify 应用配置完成后可以直接用 HTTP 接口将它变成可供业务系统调用的服务。假设你的 API Key 是app-xxxxx请求方式如下curl --location --request POST http://localhost/api/chat-messages \ --header Authorization: Bearer app-xxxxx \ --header Content-Type: application/json \ --data-raw { inputs: {}, query: 请查一下知识库里关于模型量化的说明并提炼出三个要点, response_mode: blocking, user: csdn-demo }response_mode可以填blocking或streaming。开发调试阶段推荐用blocking返回完整 JSON生产环境为了用户体验一般用streaming做流式输出。下面是一个简单的 Python 调用封装# 文件路径agent_demo/dify_client.py import requests DIFY_URL http://localhost/api/chat-messages API_KEY app-xxxxx def ask_agent(query: str, user_id: str csdn-demo) - dict: headers { Authorization: fBearer {API_KEY}, Content-Type: application/json } payload { inputs: {}, query: query, response_mode: blocking, user: user_id } response requests.post(DIFY_URL, headersheaders, jsonpayload, timeout120) response.raise_for_status() return response.json() if __name__ __main__: result ask_agent(什么是 Agent 的记忆模块) print(result[answer])这个示例是一个通用的接入范式。你可以把它嵌到飞书机器人、Web后端、命令行工具里让任何入口都具备智能体能力。6. 运行结果与效果验证完成上面的示例后需要从三个层面确认系统真的能工作。6.1 验证模型层执行示例二后正常输出的是一段结构清晰的中文回答。判断标准不是内容“好不好”而是进程没有报错返回文本非空。如果模型回答出现“API 连接错误”第一步先检查curl http://localhost:11434/api/tags是否能列出模型列表。6.2 验证知识检索层在 Dify 后台测试知识库问答时可以打开“日志”面板观察每次请求的检索链路。关键看两点是否检索到了相关文档片段模型是否引用了检索内容而不是自己编造。如果检索结果为空多半是文档分段不合理或者 Embedding 模型没有配置正确需要回到知识库做分段调整。6.3 验证 API 层通过curl调用 Dify 接口如果请求成功返回的 JSON 会包含answer、conversation_id、message_id字段。其中conversation_id很重要后续多轮对话需要把它原样传回否则智能体会丢失上下文。{ answer: 知识库中提到模型量化是将参数从高精度转换为低精度的过程..., conversation_id: abc123..., message_id: msg-001 }只要answer非空且HTTP 状态码为 200就说明整条链路已经打通客户端 → Dify → 本地开源模型 → 知识库检索 → 回复。7. 常见问题与排查思路我在不同项目里见过很多类似的问题这里列出一份高频问题清单问题现象可能原因排查方式解决方案连接 Ollama 失败Ollama 服务没启动或端口被占用curl http://localhost:11434/api/tags启动ollama serve查看端口占用容器内访问不到宿主机模型使用了localhost而不是host.docker.internal在容器内curl host.docker.internal:11434改用host.docker.internal并开放防火墙模型回答质量差模型太小或 Prompt 表达不清查看 Dify 日志中检索到的上下文换更大模型或优化 system promptAgent 不调用工具tool 描述太模糊或模型不支持复杂 tool calling在编排页面测试单个工具精简工具描述使用 tool 字段明确参数格式Dify 镜像拉取慢网络原因查看 Docker 拉取日志配置镜像加速执行docker compose pull显存不够导致 OOM模型参数量过大执行ollama ps查看显存占用换小模型或使用量化版如qwen2.5:3b一个容易被忽略的问题是本地 CPU 推理速度很慢容易触发 API 超时。如果 Dify 或客户端设置的超时时间太短模型还在生成时请求就被中断了。解决办法是把超时时间调大或者减少max_tokens。8. 最佳实践与工程建议跑通 demo 只是第一步。如果要把它变成生产系统下面这些建议值得参考。8.1 模型选型不要只盯评测分数评测分数高不等于在 Agent 场景里好用。优先选择社区反馈中“工具调用稳定”的模型并且用你真实的工具 Schema 去做回归测试。建议准备一组固定的测试用例每次换模型或升级版本后都跑一遍防止模型更新带来隐形行为变化。8.2 把模型层做成可替换的接口上面的示例中本地模型和 Dify 都兼容 OpenAI 协议。建议在项目里专门封装一层 model provider不要直接在业务代码中写死某个模型的 URL。这样一旦生产环境需要切换到更大的闭源模型或者自建 vLLM 集群只需要改配置不用改业务逻辑。8.3 工具调用要有权限边界Agent 可以调用外部工具这既是能力也是风险。生产环境要对每个工具做鉴权不能给 Agent 一把万能钥匙。例如让 Agent 连接数据库时应该使用只读账号调用企业 API 时要限制 IP 和请求频率。还要设计人工审批节点涉及高风险操作删除数据、转账、发布内容必须停下來等确认。8.4 建立可观测性和评估体系每个 Agent 请求都应该记录用户问题、模型决策链路、调用过的工具、工具返回结果、最终回复、耗时和 token 消耗。这些日志不仅能帮你定位问题也是未来优化 Prompt 和模型调优的数据基础。评估时不要只看单个回答好不好要构建一个包含几十到上百条真实场景的评测集每次改动都对比一次准确率。8.5 能用工作流就不要强行用 AgentAgent 很酷但成本高、不稳定。如果你的业务场景只有固定的3个分支用工作流十秒就能跑完而且结果可预期。只有决策路径复杂、需要模型反复判断的情况才值得引入 Agent。一个比较务实的方式是外层先用工作流做粗粒度路由路由到复杂场景后再触发 Agent 子流程。8.6 开源模型与闭源 API 混合使用开源模型和闭源 API 不是二选一。很多团队的做法是简单请求走本地小模型长尾复杂的请求走闭源大模型或者用开源模型做前置筛选把最高价值的请求提升给更贵的模型。这样既保住质量又能控制成本。9. 总结与后续学习方向这次柏林 GTC 大概率会有大量关于智能体、开源模型和硬件协同的讨论。但真正能让你在现场不焦虑的不是又多看了哪款新品而是你自己已经跑通过一条最小链路开源模型加载、本地知识库、工具调用、API 接入。这套链路并不复杂但它重新定义了 AI 应用开发的最小单位。过去你可能认为“大模型产品 一个 Prompt 一个 API”现在你更清楚智能体是一个由模型、工具、记忆、控制流组成的系统工程。开源模型让这个系统有了透明、可控、可定制的大脑而 GTC 这样的技术会议只是帮我们更快看到行业下一步的演进方向。如果你刚接触智能体建议先照着本文跑通 demo不要一开始就追求多 Agent 协作。先让一个 Agent 在一个业务场景里稳定工作再考虑复杂编排。可以继续关注的方向包括工具调用协议的标准化、长上下文管理、多 Agent 协同模式、以及基于开源模型的持续微调与评测体系。在踏上前往柏林的航班之前我会先把上面的最小 Demo 再跑一遍。技术会议的热度退得很快真正能留下的是自己亲手跑通的那套流程。 
