这大概是我这两年被问得最多的一个问题想做一个AI智能体到底从哪里下手有人一上来就啃LangChain源码有人报了一堆课却卡在环境配置上也有人天天看概念科普结果连一个能对话的Demo都没跑起来。我自己趟过一遍之后最大的感受是如果你是第一次接触智能体开发真的没必要先碰底层先把一个完整可用的智能体在平台上跑通再回头研究内部机制效率会高得多。这篇文章就是基于阿里云百炼平台从零开始带你把第一个AI智能体搭出来。不管你是后端开发、算法工程师还是产品经理、运营同学只要照着下面的步骤走大概率能在一个小时内看到一个能回答问题、能按流程执行任务的智能体。这也是我计划写的系列文章第一篇重点放在跑通和理解核心逻辑上。1. 为什么选百炼平台和框架派相比它到底赢在哪里先说一个可能得罪人的结论对于大多数应用开发者和业务人员来说自己从零搭一套智能体技术栈性价比真的不高。我可以明确告诉你我自己早期就是框架派觉得不写代码就没有技术含量后来被现实狠狠教育过。1.1 框架派绕不开的三座大山第一座大山是依赖管理。你以为装好LangChain就够了还需要装模型SDK、向量数据库、Embedding模型、Agent运行时、各种工具包。光是让Python环境不冲突就能折腾一个晚上。我记得有一次装某个向量库的底层依赖直接把系统里的OpenSSL搞坏了后面所有的HTTPS请求都报错。第二座大山是调试链路。框架给你的只是基础组件当智能体输出不对时你得同时排查大模型调用参数、提示词、工具调用结果、记忆管理逻辑。你根本分不清是哪个环节出了问题因为日志分散在各个模块里。排查一个bug花掉两三个小时是常态。第三座大山是部署运维。本地跑通只是第一步上线还要考虑API网关、鉴权、限流、弹伸缩、日志采集。这些对于专职SRE不算什么但如果你只是一个想做点AI应用的个人开发者或小团队这一套下来直接劝退。1.2 平台派解决的是最后一公里问题百炼这类平台走的是另一条路把大模型能力、智能体编排、知识库、插件都变成可视化配置和API服务你只需要关注业务本身。我用一个类比来解释框架派就像是自己买零件组装电脑折腾但不一定兼容平台派就像是买品牌整机开箱即用出问题了有统一售后。百炼平台做的事情就是把模型接入、工具调用、记忆管理、知识库、工作流这些复杂组件全部封装成开箱即用的服务让你把精力放在提示词设计、业务流程梳理和效果调优上。我个人认为百炼平台对下面几类人价值最大第一次接触AI智能体的开发者想快速建立整体认知有明确业务场景的团队比如要做智能客服、商品推荐助手、内容生成工具想先做个MVP验证效果非纯技术背景的产品、运营同学他们懂业务但写不了太多代码可视化编排几乎是唯一能独立搭智能体的方式。1.3 平台派的不完美也要提前说当然平台方案也有它的问题。最大的限制是灵活性不如自己写代码特别是当你需要自定义非常冷门的模型推理逻辑或者对接完全不兼容的私有化系统时平台反而会碍手碍脚。此外如果调用量大平台费用长期看可能比自己部署开源模型更贵。但话说回来先用平台快速验证业务假设再决定是否自研底层是成本最低的路径。这个决策逻辑我后面还会多次提到。2. 动手前的准备账号开通与关键资源获取这一步没什么技术含量但很多人会卡在细节上比如找不到入口、不知道要不要实名认证、搞不清API Key在哪里复制。我把完整流程写清楚。2.1 开通百炼服务如果你还没有阿里云账号先去官网注册一个这一步不需要我多讲。注册后需要完成实名认证个人认证就行企业认证后面再说个人认证也能正常使用百炼全部功能。然后进入阿里云官网搜索百炼或者在大模型服务分类下找到百炼大模型应用开发平台点击进入产品页后开通服务。开通过程基本是点几个按钮的事不需要付费平台本身是后付费模式也就是先用后付。这里有个容易忽略的点建议开通时就把服务协议和数据处理说明看清楚特别是涉及企业数据的内容。如果你的智能体会处理敏感业务数据建议直接联系销售确认数据隔离方案不要只看默认的控制台说明。2.2 获取API Key开通服务后在控制台右上角找到账号头像点击下拉菜单里的API-KEY管理就能看到系统自动生成的一串密钥。这串Key是你后续调用模型API和智能体API的凭证作用相当于你的密码。一键复制保存好可以在本地环境变量里配置。以Mac/Linux为例export DASHSCOPE_API_KEYsk-xxxxxxxxxxxxxxxxxxxxxxxxWindows PowerShell用户则是$env:DASHSCOPE_API_KEYsk-xxxxxxxxxxxxxxxxxxxxxxxx这里我强烈建议群里、文档里、代码仓库里任何时候都别贴完整的API Key。这玩意儿一旦泄露别人可以拿你的Key去调用模型费用全算你头上。我曾经见过有人把Key提交到GitHub公开仓库几分钟内就被爬虫抓走账号直接被刷爆。2.3 RAM子账号与团队协作配置如果你是个人开发者直接用主账号的Key就行。但如果是团队协作我建议花两分钟创建一个RAM子账号只授权百炼相关权限。这样做的好处有两个一是每个成员有自己的Key出了问题能定位到人二是可以随时回收某个成员的权限不需要改主账号信息。在阿里云RAM控制台创建用户时勾选编程访问系统会生成子账号的AccessKey ID和AccessKey Secret。然后在授权策略里选择AliyunBailianFullAccess百炼平台完全访问权限就可以了。2.4 费用意识和免费额度百炼平台是后付费模式每天产生的费用会在次日扣除。不同模型的价格差别很大通义千问系列里的轻量模型非常便宜但能力更强的旗舰模型价格会高一些。刚入门阶段我建议先用免费额度或低成本模型跑通流程不要一上来就上最强模型。特别注意工作流中每执行一次LLM节点就会产生一次模型调用费用如果工作流里串联了多个LLM节点一次请求可能产生多次费用。调试阶段要控制测试频率不要开着自动化脚本反复刷测试用例。3. 第一个智能体Demo不写一行代码也能跑通准备工作做好后我们直接进入正题。这一节我会带你创建一个最简单的智能体它能够根据你设定的角色和指令进行问答对话。这个Demo的意义在于让你理解智能体最基本的三要素模型、提示词、交互。3.1 控制台入口与项目空间概念进入百炼控制台后你会看到左侧菜单有智能体应用工作流知识库插件等入口。在开始创建之前建议先建立自己的业务空间或项目分组。如果是个人学习建一个测试项目就够了如果是团队建议按业务线划分比如客服机器人商品推荐助手这样后续管理和权限隔离都方便。3.2 创建智能体应用模型选择点击智能体应用进入应用列表页点击创建应用。填写应用名称比如我的第一个智能体然后进入应用配置页面。第一个要选的是模型。百炼平台默认提供多个通义千问系列的模型以qwen-plus和qwen-max为主力还有轻量级的qwen-turbo。我给你的建议是模型适用场景特点qwen-turbo简单问答、分类、抽取响应快、成本低qwen-plus日常任务、内容生成综合能力均衡qwen-max复杂推理、长文本、代码生成效果最强、成本较高初次体验选qwen-plus就行效果和成本的平衡点比较好。你可以在应用配置页面随时切换模型不影响已发布的版本所以不需要在这一步纠结太久。3.3 提示词才是灵魂System Prompt设计很多新手拿到一个智能体后第一反应是这模型是不是不行其实八成是提示词没写好。百炼平台的智能体应用核心就是一段System Prompt系统提示词它决定了智能体的角色、任务边界、回答风格和约束条件。我给你一个可以直接套用的结构你是一个[角色]专门负责[任务描述]。 你的工作流程 1. 先理解用户需求判断是否属于你的职责范围 2. 如果属于给出专业、准确的回答 3. 如果不属于礼貌告知用户你无法处理并引导到正确渠道。 回答要求 - 语言简洁但完整避免空话套话 - 如果信息不足明确告知用户不要编造 - 涉及具体数据时标注数据来源如果有知识库。 禁止事项 - 不要回答与本职无关的问题 - 不输出任何违法违规内容。把这段替换到系统提示词配置框里你会明显感觉到智能体的回答质量比空白提示词时高一个档次。这个结构的核心逻辑是定义角色、定义流程、定义风格、定义边界。3.4 在线体验与发布配置好提示词后右侧的预览窗口可以直接对话测试。你可以问几个常见问题看看它能不能按预期回答、语气是否统一、边界是否清晰。测试满意后点击发布系统会生成一个版本的智能体应用并提供一个API调用接口。这样它就不只是控制台里的一个玩具了你可以把它接入小程序、Web网站、钉钉机器人、企业微信等等。发布后还可以随时返回修改并重新发布线上保持的仍然是上一个稳定版本不会因为你的改动直接中断线上服务。百炼平台的应用发布其实还支持生成一个临时分享链接你可以在没有服务域名的条件下先把Demo发给同事体验。对于快速验证产品想法来说这个功能非常实用——不需要后端开发不需要申请公网IP只需要一条链接。4. 工作流搭建让智能体从有问必答变成按流程办事单纯的问答式智能体适合做客服和聊天助手但如果你想做一个能干活的智能体比如商品推荐助手、工单分类器、数据查询机器人那么就必须引入工作流。工作流是百炼平台里最有价值、也是很多人觉得最难理解的部分。我尽量讲清楚它的本质。4.1 什么是工作流为什么需要它工作流本质上是把智能体的执行过程拆成多个步骤用可视化的方式编排起来。每一步可以是一个大模型调用、一个条件判断、一个外部API请求、一个知识库检索等等。智能体不再直接拿着用户问题去问大模型而是按你设定的逻辑一步一步执行。我拿AI商品推荐智能体举例用户问给我推荐一款适合跑步用的蓝牙耳机如果只是普通问答模型的回答可能很泛甚至推荐出一个线下根本没货的商品。而用工作流你可以设计成理解用户意图提取关键条件跑步、蓝牙耳机、预算去商品知识库检索筛选符合条件且库存充足的商品把筛选结果交给大模型生成结构化推荐理由最终输出给用户。这样做的好处是每一步都可控、可调试、可优化而不是把全部压力交给大模型自由发挥。4.2 一个商品推荐场景的完整搭建过程进入控制台的工作流页面点击创建工作流命名后进入画布编辑界面。在百炼的工作流画布中你会看到左侧有各种节点类型。最常用的有开始节点接收用户输入是工作流的起点大模型LLM节点调用大模型处理文本条件判断节点根据某个条件分流知识库检索节点从指定知识库召回相关内容代码节点执行一段Python/Java代码做数据转换结束节点返回最终输出。我来演示一个最简版本先通过LLM节点提取用户需求再通过条件判断节点分流最后通过LLM节点生成推荐语。第一步设置开始节点参数名可以叫user_query类型为字符串用于接收用户的问题。第二步拖入一个大模型节点命名为意图理解。模型选择qwen-plus输入参数引用开始节点的user_query提示词写你是一个需求分析器。请从用户问题中提取商品类别、使用场景、预算范围。 输出格式为JSON例如 {category: 蓝牙耳机, scenario: 跑步, budget: 300-500元} 如果用户没有提到预算budget字段设置为未指定。这里的关键是让大模型输出结构化JSON而不是自然语言这是工作流开发的常用手法。因为后续条件判断和知识库检索需要准确的字段值自然语言很难被程序逻辑直接消费。第三步拖入条件判断节点判断预算是否指定。如果指定走知识库检索分支按价格过滤如果未指定走直接生成推荐分支让模型按销量优先推荐。第四步在知识库检索分支后接一个LLM节点把检索结果和用户问题一起传入生成最终的推荐回答注意在提示词里要求模型基于检索结果作答不要自行编造商品信息。第五步所有分支汇聚到结束节点输出最终结果。这样整个商品推荐工作流就搭好了。你可以先点右上角的运行按钮测试输入一句我想买跑步用的蓝牙耳机300以内观察每一步的输出是否符合预期。4.3 工作流调试技巧看每一步中间结果很多人在工作流跑不通的时候不知道问题出在哪。这里给你一个排查心法从第一个节点开始逐个看输出。百炼工作流调试时每次运行都会生成一份执行详情里面记录了每个节点的输入和输出。你重点关注两种异常节点报错某个节点执行失败系统会给出错误信息。最常见的是模型节点参数格式不对、API Key权限不足、知识库未关联等。输出不符合预期节点的值不是你想要的格式比如大模型没有按提示词要求输出JSON而是输出了一段解释文字。解决方式是改提示词强调必须输出JSON不要任何额外文字。还有一个非常实用的技巧在大模型节点的提示词里让模型输出固定格式同时在后续节点中用变量提取或者代码节点来解析字段。如果你后面需要解析JSON用代码节点写几行Python是最稳妥的方案。import json def main(inputs): text inputs[llm_output] try: data json.loads(text.strip().strip(json).strip()) return { category: data.get(category, ), scenario: data.get(scenario, ), budget: data.get(budget, ) } except Exception as e: return {error: str(e), raw: text}这段代码的作用是把大模型输出的JSON字符串转换为结构化的字段供后续节点引用。你可能会问为什么要多此一举因为工作流里的条件判断、知识库检索参数都需要精确的字段值而大模型的输出天然是自由文本所以必须用代码节点做一次格式化。4.4 工作流的调试与发布在画布中调试时建议先跑分支中的最短路径再逐步覆盖复杂分支。比如商品推荐场景先测试没指定预算的分支确认产出正常后再测试指定了预算且知识库能检索到结果的分支最后测试指定了预算但知识库没有匹配结果的兜底分支。兜底分支很容易被忽略。如果知识库检索结果为空你直接让大模型生成推荐语它就很容易开始胡编。正确的做法是在检索节点后面加一个条件判断判断检索结果是否为空为空时换一段更温和的回答比如抱歉暂时没有找到符合您要求的商品您可以尝试放宽预算范围。工作流调试无误后点击发布它就会变成一个可被外部调用的API服务。之后再创建智能体应用时可以选择关联已有工作流这样智能体就不再是简单的问答机器人而是有了固定的业务执行流程。这也是我强烈推荐的架构方式应用负责对话体验工作流负责业务逻辑各司其职。5. 知识库和插件给智能体装上业务大脑与行动手脚一个只有模型提示词的智能体本质上是一个什么都懂一点、但什么都不精通的通用助手。要让它在你的业务场景里真正好用通常还需要两样东西知识库和插件。5.1 知识库解决的是什么问题先说知识库。大模型的知识截止时间是固定的它不知道你公司内部的最新政策不知道你店铺里目前在售的具体商品也不知道你产品的技术参数。如果你直接问它它只能根据历史训练数据猜猜错了就叫幻觉。知识库的作用就是把你的私有知识——文档、表格、网页——预先切成向量片段存储起来当用户提问时系统先从知识库里检索出相关片段再让大模型基于这些片段回答问题。相当于给模型配了一份开卷考试资料它只需要从资料里找答案而不是凭记忆编造。5.2 上传文档与检索配置在百炼控制台的知识库页面点击创建知识库然后上传你准备好的文档。支持PDF、Word、TXT、Markdown等常见格式也可以直接导入网站URL或API拉取数据。上传后平台会自动对文档进行解析和切分。这一步有一个重要参数分段长度。分段太短上下文不完整检索出来缺乏背景分段太长又容易把不相关的内容混在一起而且超出模型单次接受的信息量上限。官方默认的分段长度通常是合理的但如果你发现检索效果不好可以通过高级配置手动调整。我个人的经验是对于说明书类的文档分段可以长一点500~800字保留完整逻辑对于FAQ类问答文档分段短一点200~400字让每条问答尽量独立。创建好知识库后还需要在智能体应用或工作流中关联它。在智能体应用的配置页面有一个知识库关联项添加后会有检索增强生成的选项——这里我强烈建议开启它会在模型回答前自动插入检索到的知识片段效果比你手动拼接知识内容再提问好得多。另外注意知识库的更新并不是即时的。当你修改了知识库里的文档需要在知识库管理界面触发重新导入或增量更新操作线上生效一般有几十秒到几分钟的延迟。如果用户在旧版本期间提问可能会读到旧的知识内容。5.3 插件能力让智能体真正做动作智能体如果只能回答问题价值还是有限。真正让它能干活的是插件。百炼平台的插件系统把很多常见能力封装成了可调用的工具比如HTTP请求插件智能体可以调用外部API获取实时数据天气、股票、快递状态数据库查询插件可以通过配置连接数据库执行SQL查询返回结果图片生成/语音合成插件结合大模型和AIGC能力生成多模态内容自定义插件如果你有自己的系统API可以通过自定义插件的方式接入相当于给智能体增加一个手。插件的本质是工具调用。智能体在收到用户请求后会判断是否需要调用某个工具然后生成一个结构化的调用参数插件服务执行后把结果返回给模型模型再组织最终答案。举个例子用户问帮我查一下订单PS2026001的物流信息。如果智能体接入了订单查询插件它会先把订单号从问题里提取出来调用你系统的物流查询接口拿到轨迹数据后再回答用户。如果没有插件它只能回答我无法查询您的订单请联系客服。插件配置的过程不复杂最难的其实是让智能体在合适的时候正确调用插件。这需要通过提示词反复引导。一个可行的方法是在系统提示词里明确告诉它当用户询问物流/订单/售后等问题时你必须调用【订单查询】工具来获取信息不要凭经验回答。5.4 知识库工作流插件的典型联动这三个能力组合起来基本可以覆盖大多数企业级智能体场景。我给一个通用的架构参考用户输入 → 意图分类LLM节点 → 如果是知识类问题 → 知识库检索 → 基于检索结果生成回答 → 如果是操作类问题 → 判断需要哪个插件 → 调用插件API → 用返回结果生成回答 → 如果是复杂业务流程 → 走多步骤工作流这个架构看起来简单但能解决80%的实际问题。你在搭建时不需要一上来就设计得特别复杂而是先从一个最简单的链路跑通再逐步加节点。6. 实测中遇到的5个问题与排查思路这一节我想分享一些我在百炼平台上实际踩过的坑。这些问题在官方文档里不一定写着答案都是比较实际的运维和调优经验。6.1 提示词过长导致响应变慢我第一次搭建智能体时想把所有业务规则、产品信息都塞进System Prompt结果发现模型响应速度明显变慢而且经常回答得答非所问好像记不住前面几十行规则。后来才意识到大模型对超长上下文的处理是有代价的不仅更慢更贵而且过长的提示词会稀释关键指令的权重。我的优化思路是把固定规则放在System Prompt最前面动态内容比如用户订单信息放在末尾的对话历史中把大段产品资料移到知识库里而不是写在提示词里。6.2 知识库命中率低智能体关联知识库后回答还是经常说我不知道或者答得跑偏。第一反应是知识库是不是没生效后来通过调试发现是检索结果根本没有被模型正确利用。解决办法有三步第一步确认知识库切分粒度是否合适第二步在提示词里明确要求请基于以下参考资料回答如果资料中没有相关信息请直接说明第三步调整检索的Top K值召回数量默认可能只召回3段如果你觉得信息不够可以调到5~8段。这里有一个细节知识库检索本身就是一门调参学问不要指望一次配置就完美。建议在控制台里查看每次提问时实际召回了哪些片段、命中的是文档的哪一部分然后反推是切分问题还是关键词覆盖问题。6.3 工作流节点超时或报错工作流跑得多了偶尔会遇到某个节点报错。最常见的是大模型节点超时和上游节点输出格式解析失败。超时的问题通常不是平台不稳定而是你的提示词让模型做了太复杂的推理或生成了太长的输出。建议拆分任务一个大模型节点只负责一件事不要让它又分析、又生成、又总结。如果确实需要把模型切换为更强的qwen-max或者减少单次输出的最大Token数。格式解析失败的问题大多数是因为大模型没有严格按照你要求的JSON格式输出。开发时不要指望模型100%服从一定要在代码节点里做容错解析前面我给的Python代码就有try-except并在解析失败时给用户一个备选回答而不是直接抛异常。6.4 模型答非所问时先从提示词找原因很多初学者遇到智能体回答跑偏第一反应是换个模型。实际上大部分问题出在提示词而不是模型本身。你可以做一个小实验同样的问题先让qwen-turbo在一个精心设计的提示词下回答再让qwen-max在一个很敷衍的提示词下回答结果往往是qwen-turbo表现得更好。这说明提示词的上限决定了智能体的能力下限。在考虑换模型之前先检查几个点角色定义是否清晰输出格式是否明确是否需要给一两个少样本示例是否给了模型拒绝回答的出口6.5 版本管理线上版本和调试版本别搞混百炼平台支持发布版本和草稿版本的概念你可以在草稿状态下随便改但线上自动调用的是已发布的最新版本。看起来很简单但在团队协作时很容易出问题有人改了草稿以为线上已经生效结果用户反馈功能没变。所以我给自己定了一条规矩每次改动完成先在草稿环境里完整测试一遍再发布新版本并且写清楚版本变更说明。如果线上出现问题需要回滚也有据可查。还有一个小技巧如果你要给同一个智能体做A/B测试可以用百炼平台的多个应用来隔离分别配置不同的提示词风格然后把用户请求分流到不同应用上最后通过数据反馈判断哪个版本效果更好。以上就是这一篇的全部内容。从账号开通、API Key获取到创建第一个智能体再到用工作流串起业务流程加知识库和插件做能力增强最后聊了几个实战中的坑。整个过程中你可能会发现构建AI智能体最大的难点其实不是技术而是把业务逻辑想清楚你想让它做什么、边界在哪里、信息从哪里来、答不上来时的兜底是什么。在动手开始搭建前我建议你拿一张纸写下这几个问题的答案然后再打开控制台。下一篇我计划深入讲一个更完整的实战场景——比如把商品推荐智能体从头到尾做扎实包括数据库对接、多轮对话记忆、效果评估以及如何用大模型做自动化评测。你先把手上的Hello World跑起来我们下一篇见。