在动手之前我想先说清楚一件事这一篇不是概念科普而是要把“AI智能体到底怎么从无到有做出来”这件事拆成可以直接抄作业的步骤。我选阿里云百炼平台作为第一站是因为它把模型接入、Prompt编排、知识库、插件调用这些原本散落在各个服务里的环节统一到了一个控制台里特别适合第一次接触智能体开发的人建立整体手感。如果你正想做一个能回答产品问题、能调用工具干活、能翻资料再开口的AI助手但对着一堆大模型API文档不知道从哪下手这篇就是给你准备的。我会按照真实开发顺序走一遍从注册开通、拿到密钥到在控制台搭出第一个对话型智能体再到用Function Calling和工作流让它完成更复杂的任务。每一段都会给出可以直接复制的代码和配置也会把我踩过的坑一并列出来。1. 为什么要用百炼平台来做智能体1.1 一句话搞清楚AI智能体到底是什么先别急着上手我见过太多人一上来就写Prompt结果做出来的东西连“智能体”都算不上就是个聊天机器人。智能体和普通聊天机器人最大的区别在于它不是只靠模型脑子里那点知识回答你而是会自己判断“这个问题需不需要查资料”“要不要调个接口算一下”然后去执行再把结果整理给你。举个例子你问普通聊天机器人“上海明天适合跑步吗”它只能凭训练数据编一个答案。但你问一个真正的智能体它会先调用天气接口拿到明天的天气和空气质量再结合你预设的跑步偏好告诉你适合还是不适合。整个过程里模型负责思考和决策工具负责拿真实数据知识库负责补充私有资料这三者拼在一起才叫智能体。百炼平台做的事情就是把这三种能力都打包好让你不用自己一个人搭模型服务、写Prompt管理框架、还要处理工具调用的复杂状态。你只需要在控制台或者代码里声明“我要用哪个模型、挂哪个知识库、暴露哪些工具”它就把这些组件编排成一个可对外服务的智能体应用。这个思路跟传统软件开发的“组件复用”很像只不过这里的组件变成了模型、知识库和插件。1.2 百炼平台解决了智能体开发的哪些核心难题我在自己动手之前其实试过直接拿大模型API裸奔。结果发现要想把一个智能体做成产品要处理的麻烦事一件接一件。模型选择困难官方模型一出一堆instruction-following能力各不一样你得自己对比测试才能知道哪个模型适合你的业务。知识库接入费劲私有文档要切块、向量化、召回每一步都得自己写代码还要考虑不同格式PDF怎么解析。工具调用状态管理模型说要调用某个函数你得自己解析参数、执行、回传结果多轮对话里还要不断维护历史上下文。发布和运维做完了要提供API给别人调用要考虑并发、限流、Token计费这些对小白来说全是门槛。百炼平台把这些事情全收敛到了后台。模型用哪个、知识库怎么挂、插件怎么开都在控制台里点点鼠标就能完成。它本身也提供OpenAI兼容的接口意味着你以前熟悉的SDK和代码习惯可以继续用不需要重头学一套全新的调用方式。我比较推荐新手先把控制台的“智能体应用”功能摸熟因为它会把“对话式”“工作流式”两种应用形态放在同一个入口里。先用对话式快速验证想法等业务复杂了再平滑迁到工作流式。这个过渡路径很顺不会浪费你前期的尝试。另外百炼继承了一个很实际的优势它是国内可直接访问的服务网络环境稳定。这一点对要做线上业务的人来说很重要不用折腾额外的网络配置合规省心。2. 开荒准备账号、权限与模型接入2.1 开通百炼服务并完成模型权限确认第一步是登录阿里云账号然后在控制台里找到“百炼”产品入口。如果之前没开通过会看到一个开通引导页面需要同意服务协议并确认开通。这里要提个醒百炼属于后付费产品开通本身不收费但一旦开始调用模型就会产生Token费用。新手阶段建议在控制台右侧的“费用”区域设置一个消费阈值提醒别稀里糊涂跑了一晚上压测第二天看到账单才傻眼。开通后进到百炼控制台首页你会看到模型广场、应用中心、知识库、插件中心这些模块。第一次进来别急着点到处乱试先去“模型广场”确认你要用的模型是否已经在当前区域开放。不同模型的开放时间不一样有些新模型可能只在特定地域上线如果你在API调用时报“model not found”大概率就是这里没确认清楚。我建议新手直接选qwen-plus作为主力模型。它在理解能力、指令遵循和响应速度之间比较均衡价格也适中适合开发和测试。如果是非常简单的任务可以降到qwen-turbo要做复杂推理或工具调度再考虑qwen-max。先用通用默认配置跑通全链路再根据效果换模型这是性价比最高的路径。2.2 获取API-Key与第一行调用代码模型权限确认后接下来就是拿钥匙。在百炼控制台右上角点你的头像进入“API-Key管理”创建一个新Key。这个Key是调用所有百炼服务的主凭证建议把它保存在环境变量里不要写死在代码或者传到公开仓库。我用的是Linux/macOS下写入~/.bashrc的方式export DASHSCOPE_API_KEYsk-xxxxxxxxxxxxxxxxWindows用户可以在系统环境变量里新增一条效果一样。拿到Key之后先不急着去控制台拖拽画布我习惯先写一段最小调用代码确认模型服务和网络链路是通的。百炼提供了DashScope Python SDK也可以直接用OpenAI SDK访问它的兼容接口。我下面两种方式都放出来你看哪个顺手用哪个。先看DashScope SDK的写法import os from dashscope import Generation response Generation.call( modelqwen-plus, prompt你好用一句话介绍你自己。, max_tokens256, temperature0.7, ) if response.status_code 200: print(response.output.text) else: print(请求失败, response.code, response.message)再看OpenAI兼容接口的写法import os from openai import OpenAI client OpenAI( api_keyos.getenv(DASHSCOPE_API_KEY), base_urlhttps://dashscope.aliyuncs.com/compatible-mode/v1 ) completion client.chat.completions.create( modelqwen-plus, messages[ {role: system, content: 你是一个乐于助人的助手。}, {role: user, content: 你好用一句话介绍你自己。} ] ) print(completion.choices[0].message.content)两种方式都能跑通。我个人在后续的智能体开发中更常用第二种因为它和我团队里其他工具链比如LangChain、LlamaIndex能直接兼容代码迁移成本低。你要注意OpenAI兼容接口的base_url必须带compatible-mode这个路径漏掉就会报404或者连接错误。很多人一开始卡在这里并不是Key的问题。3. 5分钟快速搭出第一个对话型智能体3.1 控制台创建智能体应用的完整流程代码验证通过后我们再回到控制台用可视化方式搭一个智能体。找到“应用中心”点击“创建应用”选择“智能体应用”。创建之后会进入一个配置页面分为三大块模型选择、人设与Prompt、技能配置。先把模型选择成刚才验证过的qwen-plus其他参数先不动。重点看人设和Prompt的配置这里决定你的智能体“像不像”。我在表单里给每个智能体都准备了一套统一的Prompt骨架用起来效果不错。这套骨架是角色定义你是谁服务对象是谁。任务边界你能做什么不能做什么。回答风格简洁还是详细口语还是书面。兜底策略无法回答时怎么办。比如我想做一个“健身搭子”智能体Prompt可以写成你是一个专业的健身助手擅长为用户制定训练计划和分析动作细节。 你只能根据科学健身知识回答不能给医疗诊断或药品建议。 回答风格要友好且简洁多用短句和列表。 如果用户提到明显不合理的极端减脂方案要先提醒风险再提供替代建议。这里有个很关键的操作在“技能”区域先不要勾选任何插件和知识库保持一个纯净的对话智能体。这样能帮你判断当前回答质量到底来自模型本身还是来自外部能力后续再加东西时心里才有数。保存之后可以点击右侧的“预览”面板先聊几句或者直接调用“发布”获取一个内部测试API。不用等到完全满意再测试快速试错才是正路。3.2 三个Prompt设置的实战心得很多人觉得Prompt随便写写就行实际上Prompt写得好不好直接决定智能体的成败。我整理了我自己踩坑后总结出的三点一、把“不要做什么”写清楚比“要做什么”更重要。模型最怕没有边界。如果只写“你是客服助手”它可能连理财产品推荐都给你编出来。但如果你写上“涉及账户余额、交易密码必须引导到人工客服”它就会在越界情况下主动收敛。二、给模型固定的输出结构。比如你想让智能体给出训练计划可以在Prompt里强制规定输出格式训练目标、动作列表、每组次数、休息时间、注意事项。模型对明确的结构化要求响应很好这样后续用程序解析输出也方便。三、设置好兜底回复。任何智能体都会遇到不懂的问题与其让模型硬编不如引导它说“这个问题我暂时无法确认建议你联系人工客服”。用户更反感一本正经的胡说八道而不是坦诚的否定回答。顺便说一句“模型参数”里的temperature值我一般会调到0.3以下。智能体应用是干活的不是写诗过高的随机性会影响回答的稳定性。如果你做的是营销文案生成这类创意任务再适当调高也不迟。4. 从对话到干活让智能体会调用工具4.1 Function Calling原理与触发条件到这里你已经有了一个能聊天的智能体。但这个程度还远远不够真正让智能体“干活”的关键在于让它可以调用外部工具。大模型训练数据不是实时的它没法知道某个商品现在的价格也没法查到最新的天气。所以我们要通过Function Calling的机制把工具能力暴露给模型。机制本身可以这样理解你准备好几个函数说明告诉模型“有这些工具可用”模型在回答前先判断用户意图是否匹配某个工具。如果匹配它不会直接回答而是输出一个结构化的“调用请求”把函数名和参数都填好。你的程序收到这个请求后执行实际函数比如查数据库、调API再把结果塞回给模型模型基于结果生成最终回答。为了让模型正确决定“要不要调用、调用哪个”工具定义的质量才是关键。我贴一个商品搜索工具的示例tools [ { type: function, function: { name: search_products, description: 根据用户需求关键词搜索可购买的商品列表通常用于用户想购物、选商品、比价时调用。, parameters: { type: object, properties: { keyword: { type: string, description: 商品关键词例如跑步鞋、降噪耳机 }, max_price: { type: number, description: 用户能接受的最高价格单位元如果用户没说不填 } }, required: [keyword] } } } ]这里有个容易被忽略的细节description里要写清楚“什么时候该用这个函数”而不是只写“这个函数是干什么的”。模型是靠这些描述和用户输入做匹配的你描述得越贴近真实场景它唤起工具的准确率就越高。我刚做开发时习惯把description写成“Search products”结果模型经常该调不调改成“当用户想购物、选商品、比价时调用”之后准确率立刻上了一个台阶。4.2 实战案例做一个商品推荐顾问智能体上面是工具定义下面我把完整调用流程串起来。假设我们要做一个“商品推荐顾问”用户说出需求后它会先调商品搜索接口拿到候选列表再推荐。第一步先封装真实的商品搜索函数。这里为了演示我用一个本地函数模拟实际开发中你只需要把这个函数替换成内部商品服务或者第三方电商API即可def search_products(keyword: str, max_price: float None): # 模拟商品库查询 all_products [ {name: 轻量跑鞋A, price: 399, score: 4.8}, {name: 缓震跑鞋B, price: 699, score: 4.9}, {name: 竞速跑鞋C, price: 1299, score: 4.7}, ] result [p for p in all_products if keyword in p[name]] if max_price: result [p for p in result if p[price] max_price] return result第二步把用户消息、工具定义和模型一起发出去拿到模型的工具调用请求import json from openai import OpenAI client OpenAI( api_keyos.getenv(DASHSCOPE_API_KEY), base_urlhttps://dashscope.aliyuncs.com/compatible-mode/v1 ) messages [ {role: system, content: 你是一个商品推荐顾问根据用户需求调用搜索工具获取商品信息再给出购买建议。}, {role: user, content: 我想找一双适合长跑的鞋预算500以内有什么推荐} ] resp client.chat.completions.create( modelqwen-plus, messagesmessages, toolstools, ) msg resp.choices[0].message print(msg)第三步判断模型是否返回tool_calls如果有就执行对应函数并把结果追加到对话里再让模型生成最终回答if msg.tool_calls: tool_call msg.tool_calls[0] args json.loads(tool_call.function.arguments) if tool_call.function.name search_products: products search_products(**args) messages.append(msg) messages.append({ role: tool, tool_call_id: tool_call.id, content: json.dumps(products, ensure_asciiFalse) }) final_resp client.chat.completions.create( modelqwen-plus, messagesmessages, toolstools, ) print(final_resp.choices[0].message.content)整个链路跑通之后你就拥有一个真正意义上“会干活”的智能体了它可以自主判断用户想购物调用搜索工具拿真实数据回来组织推荐话术。后续你再加天气查询、商品下单、物流查询都是复制这个套路往tools列表里继续挂新函数而已。这也是我建议先从代码层面理解Function Calling的原因控制台上的插件配置只是帮你降低了这一步的门槛但原理你没搞懂一出问题就抓瞎。4.3 知识库让智能体拥有私域专业知识提到知识库之前先说个前置需求。商品推荐场景里如果你卖的是自家产品光靠搜索引擎不够还需要让智能体了解产品手册、售后政策、FAQ这些私有资料。百炼的“知识库”模块就是干这个的。使用流程不复杂在控制台“知识库”里新建一个知识库上传你的文档支持PDF、Word、txt、Markdown等格式平台会自动做切片和向量化。上传完成后需要等索引状态变成“已完成”这个过程中不要急文档多的话可能要等几分钟。切片策略我建议关注一下默认的“自动分割”适合大多数通用文档但如果是纯文本的产品FAQ我会选择“按标题分割”或手动指定分隔符这样每个切片会更完整避免问题被切断导致检索不准。检索测试中心可以让你直接输入问题看召回结果这一步特别实用能提前发现“为什么智能体答不上来”的根源。最后在智能体应用配置里挂上这个知识库再在Prompt里加一句“优先根据知识库内容回答知识库没有的不要瞎编”它就变成一个懂你业务的专家了。对了这里的优秀实践是只回答知识库覆盖范围内的问题外部问题温柔拒绝能显著减少错误率。5. 高级玩法用工作流把复杂步骤串起来5.1 工作流与自由对话的差别对话式智能体适合“边查边答”的开放场景但有些业务需求是固定的、步骤化的。举个例子用户提交一个售后工单你需要先分类再判断是否超期最后生成不同回复。这样的流程如果全部丢给模型自由发挥结果会很不可控。这时候就该用“工作流式智能体”。工作流不是你想象中的代码而是一张可视化的编排画布。你从“开始节点”定义好输入然后拖出LLM节点、条件分支节点、Http请求节点、结束节点把它们连成一条线每个节点只做一件小事情。这样做的好处是每个步骤都可见、可调试、可单独替换非常适合生产环境。百炼控制台创建应用时选择“工作流应用”进入画布编辑界面。左侧是节点库中间是编排区域右侧是选中节点的配置面板。我建议第一次先拖四个节点练手开始节点、LLM节点、条件分支节点、结束节点。5.2 一个售后工单自动分类的流程设计我拿“售后工单自动分类与回复”来演示这个场景比较通用也覆盖了工作流最核心的节点用法。开始节点定义输入{ user_input: }。LLM节点负责分类。模型选择qwen-plusPrompt写你是工单分类器。根据用户输入将工单分为以下三类之一售后、物流、产品。 只输出一个词不要输出其他内容。 用户输入{{inputs.user_input}}这里要特别注意工作流里的变量引用语法是{{inputs.xxx}}不同平台可能略有差别但百炼的规则会让你在节点配置里看到可选的变量列表不用硬记。条件分支节点根据分类结果做路由。你可以配置规则当LLM输出为“物流”时走物流处理分支否则走人工处理分支。这一步取代了传统后端代码里的if...else你可以在画布上直接拖出多条线每条线绑定不同条件。最后在结束节点把结果拼装返回。比如物流类返回“感谢反馈我们会核实物流状态24小时内回复”售后类返回“已创建售后工单请保持电话畅通”产品类返回“建议查看商品使用手册如果仍有问题请联系客服”。把这个工作流发布成API后你的系统只需要把用户输入POST过来就能拿到一个结构化的处理结果。相比让模型自由发挥这种方式每一步都透明出了问题也方便定位。如果你以后需要接入内部系统还可以在中间加Http请求节点调用你们的订单或库存接口整个流程就真正和业务打通了。6. 常见问题与排查技巧实录6.1 新手最容易踩的五个坑我把自己和身边朋友在百炼上踩过的坑做了个汇总。这些问题几乎每个人都会遇到建议收藏备用。问题现象常见原因排查与解决办法调用API报 InvalidApiKeyAPI-Key配置错误或环境变量未生效打开终端执行echo $DASHSCOPE_API_KEY确认是否为空空的话重新export或检查IDE环境变量配置报 model not found / InvalidParameter模型名写错或该模型未开通去模型广场复制最终准确的模型名不要手打确认当前地域是否支持该模型输出内容一直不稳定温度参数过高或Prompt边界模糊把temperature降到0.3以内并给模型更明确的输出格式约束工具调用不触发或乱触发工具描述与用户意图匹配不明确优化工具栏的description写明“什么时候该用”尽量贴近业务场景知识库回答不出来文档切片过碎、问题措辞和文档不一致、索引未完成在知识库测试中心验证召回效果调整切片策略确认文档索引状态为“已完成”后再测试这里面最隐蔽的是第二个坑。模型名字看起来都是qwen-plus但平台内部可能因为版本迭代多出qwen-plus-latest或者带日期后缀的版本。最稳妥的办法是在模型广场点击对应模型控制台会给出可直接复制的模型名别凭记忆手打。6.2 调试智能体的三个建议工具除了官方控制台自带的测试面板我再分享几个平时排查效率很高的做法。打开日志面板百炼每个应用都有调用日志记录了每次请求的输入输出、Token用量和耗时。我习惯在阿里云日志服务里关联保存百炼日志这样当用户反馈“之前能用现在不行了”时我能快速回看那一条请求到底发生了什么。用小数据集做回归测试改完Prompt或工具定义后不要只测一句话就上线。我会准备20到30个典型用户问题批量跑一遍比较前后的输出质量。这个过程手动做太费时间可以写个简单脚本循环调API把结果存到文件里逐条看。多轮对话上下文管理如果发现智能体“记不住”前面的内容多半是你在代码里没有把历史消息传进去。API是无状态的每次请求都要带上完整的messages列表。但要注意别无限增长超长后可以用截断策略保留最近的几轮对话。6.3 成本控制与安全注意事项最后说两个很容易被忽略的维度。第一个是成本。工作流应用每个节点都会消耗Token尤其LLM节点越多成本越高。我通常是先统计用户请求的日均量再估算单次请求的平均Token成本最后设置好每日消费预警。百炼控制台的用量统计里可以按应用维度看消耗不用全凭估算。第二个是数据安全。如果你上传的知识库里有内部资料千万不要把API-Key和外发接口暴露给前端页面。生产环境下请求应该统一走后端服务再由后端调用百炼API避免Key被扒走。另外如果要做面向C端的智能体建议在Prompt层加一轮内容安全检查防止用户诱导越权。最后再分享一点我的实际操作体会这套从零到一的过程走完你会发现AI智能体开发真正的门槛其实不在“调用模型”这一步而是在“你愿不愿意把任务拆成模型和工具各负责什么”。模型的强项是理解和生成弱点是事实缺失和计算不稳定工具的强项是准确和可重复弱点是死板。把它们组合好才是一个合格智能体的根基。我自己刚开始做的时候特别容易陷入一个误区总想让模型自己完成所有事。后来被现实教育了几次才学会把每个能力边界划清楚。比如让模型解释天气却不让它挂天气API它就只能瞎编。现在我的习惯是先问一句“这个信息模型真的知道吗还是应该交给工具去查”这句话能让设计质量提高一大截。这一篇先把平台侧的操作链路讲透了下一篇我打算深入讲一下工作流的常见业务设计模式以及如何把知识库的召回准确率调上去。如果你在跟着操作时遇到报错不妨先在控制台日志里看一眼具体返回信息大部分问题其实都能在错误详情里找到答案。