跳到主要内容

常见问题 FAQ

提示

云开发 AI 模块近期的更新日志请参考

AI 更新日志

入门与基础功能​

如何免费试用云开发 AI 能力？​

试用方式：

  • 新人特权：新用户首月 0 元体验。
    • 方式 1：已有小程序，通过微信开发者工具或者通过微信公众平台（登录小程序账号，使用微信云服务助手小程序开通，不需要下载开发者工具）开通云开发，首月免费（适用于未使用过云开发的用户）。
    • 方式 2：若无小程序，可先开通微搭体验版 链接
  • 之后登录 使用入口 试用 AI+ 功能。

云开发 AI Agent 能做什么?​

核心功能​
  • 多种 AI 能力：可直接调用大模型 API，或自定义 Agent 接入知识库系统。
全渠道部署​
  • 发布渠道：支持小程序、Web 网页、微信公众号/服务号及微信客服系统。
  • 模型支持：同时兼容 DeepSeek 和混元双模型。

小程序如何接入 AI?​

请参考《小程序接入云开发 AI 能力指引》： 链接

如需进一步操作或建议，请查阅该指引文档。

有没有已经开发好的云开发 AI 小程序案例?​

有。可通过以小程序体验云开发 AI 能力：

支持 DeepSeek 及智能体实时试玩。

不写代码如何发布一个 AI Agent？​

可以选择一键发布 Agent 为网页或者小程序，或者参考上述文档来发布到公众号。

如何快速创建 AI Agent?​

首先，确保已经创建过云开发环境，免费创建体验流程请参考上文如何免费试用云开发 AI 能力？

  1. 登录 AI+: Agent 后登录 使用入口 试用 AI+ 功能。
  2. 创建 Agent： 创建一个 Agent，选择模型（支持 DeepSeek/混元大模型，）填写设定信息，上传个人知识库，点击保存 Agent

是否支持快速基于 AI Agent 创建一个小程序/web 网页​

支持，且无需编码基础，零代码可以上线。

完成 Agent 创建之后，可以在保存之后的弹窗中，点击创建应用，支持发布为独立的小程序或网站

如何在现有小程序中使用？​

需要一定的编码基础，可参考参考《小程序接入云开发 AI 能力指引》： 链接

公众号是否支持接入 AI 实现智能客服？​

支持，云开发 Agent 可以一键发布到公众号和服务号作为智能客服，复用微信公众号都对话界面提供客服能力。

  1. 发布到公众号：参考 [如何快速创建 AI Agent?](#如何快速创建 AI Agent?) ,保存之后，点击发布到微信平台，选择公众号或者服务号，填写公众号的 appid，授权之后即可发布到公众号
  2. 体验对话功能：在公众号界面进行对话，即可体验

限制条件： 对于订阅号或者未认证的服务号，只能在 15 秒内进行被动回复。若消息处理时间超出这一时限，系统便会自动发送“思考中，请回复‘继续’”的提示。已经认证的服务号不受此限制。

其他方式​
  • 公众号菜单嵌入智能客服：创建完 Agent 之后可以一键生成一个应用，发布为 h5 网页，然后把地址嵌入到公众号菜单中

视频号是否可以接入 AI 实现智能客服？​

支持，可以参考上一步的 1/2 步骤，先创建完 Agent，然后选择发布到微信客服即可，微信客服支持服务视频号的用户。

云开发 Agent 是否支持企业微信智能客服?​

支持。云开发 Agent 可以发布到微信客服系统，可以参考前面流程，先创建完 Agent，，然后选择发布到微信客服即可，底层基于企业微信，能够服务外部微信客户。

DeepSeek 是否支持联网搜索？​

支持，可通过 Agent 可开启联网搜索能力，支持混元大模型和 DeepSeek

是否支持用户在对话中上传文档和图片？​

支持，通过 Agent 可在对话中上传文档和图片，支持混元大模型和 DeepSeek

是否支持用户查看历史记录？​

支持，可以使用最新的 Agent UI，默认集成了查看历史记录功能

是否支持多个会话分组功能？​

支持多会话分组功能，可参考 多会话管理

为什么 Agent 回复速度有些慢？​

请检查是否使用了 DeepSeek R1 模型， DeepSeek R1 模型思考过程较久，

可以切换到 DeepSeek V3 模型，没有思考过程，回复更快

或者也可以使用混元大模型的 Turbo S 快思考模型

是否支持对接其他平台搭建的智能体？​

支持通过函数型智能体对接其他平台的智能体，例如元器等平台开发的 Agent，支持通过 Agent UI 及小程序基础库 SDK 来调用

是否开放了 API 可以通过其他语言或者平台来调用？​

支持，模型接入接口将可以无缝对接 OpenAI SDK 等开源库，Agent 对话相关接口，可通过 HTTP 请求方式被其他平台任意语言来调用

是否支持通过服务器方式开发的小程序或者第三方开发的小程序调用？​

只要能够开通云开发，都是可以正常在小程序中使用云开发提供的 AI+能力。

已有小程序，通过微信开发者工具开通云开发或者通过微信公众平台-登录小程序-开通云开发，首月免费（适用于未使用过云开发的用户）。

开发​

如何隐藏 Agent UI 的推理思考过程？​

DeepSeek R1 等模型思考过程较久，如果希望隐藏思考过程，可以切换到混元大模型，或者切换到 DeepSeek V3 模型，没有思考过程，回复更快。

或者，在 AgentUI 中进行隐藏

小程序 Agent UI 组件​

找到如下代码进行删除

   <markdownPreview markdown="{{item.reasoning_content||''}}"></markdownPreview>

Agent UI 可视化组件​

找到思考过程，点击不可见，即可隐藏思考过程

Agent 文件上传或解析失败，如何解决？​

由于微信小程序基础库安全策略升级，文件上传功能解析流程可能受到影响，请开发者进行 Agent-UI 组件升级：

  • 小程序源码组件，请更新替换至最新版本
  • 微搭低码组件，请新建页面然后重新拖动更新 agent-ui 区块，完成后发布应用

Agent 是否查看历史对话记录？​

可以，在控制台的 Agent 详情，点击查看历史记录

是否支持通过 API 调用大模型？​

支持，可参考 AI 工具配置（OpenAI 兼容协议）。

是否支持通过 API 调用 Agent?​

支持，可参考 Agent 集成指引

Agent 中是否支持插件和工具调用？​

支持，可以通过函数型 Agent 进行开发，支持开源 Agent 框架，如 Langchain、Mastra 等，都可以通过函数型 Agent 进行适配，同时支持通过可视化开发，小程序 和 web 以 API 和 JSSDK 来调用 Agent

Agent 中是否可以对接外部 API 或者外部数据库？​

支持，可以通过函数型 Agent 进行开发，通过工具调用，对接外部 API 或者外部数据库，同时支持通过可视化开发，小程序 和 web 以 API 和 JSSDK 来调用 Agent

Agent 中是否支持可视化工作流？​

暂不支持可视化工作流编排，可通过函数型 Agent 进行代码编排实现复杂的 Agent 功能

是否支持对接元器/LKE 等其他 Agent 开发工具提供的 Agent？​

支持，可以通过函数型 Agent 进行适配，可以无缝对接元器/LKE 等 Agent 开发工具提供的 Agent，同时支持通过可视化开发，小程序 和 web 以 API 和 JSSDK 来调用 Agent

函数型 Agent 是否可以对接公众号/服务号/微信客服？​

支持，可参考 对接微信公众号/服务号 和 对接微信客服

UniApp/Taro 等框架如何使用云开发 AI 能力？​

如果使用微信 Donut 多端框架开发应用，可以使用 wx.cloud.extend.AI 接口来调用云开发 AI 能力，和微信小程序中保持一致，具体可参考多端框架 wx.cloud.extend.AI 接口

UniApp/Taro 可以通过分别调用微信基础库和 JSSDK 来实现多端调用，参考 SDK 初始化

其他语言或者框架如何使用云开发 AI 能力？​

可以通过 HTTP API 来调用，参考 HTTP API

发布与部署​

小程序中使用了 AI 能力，正式上线前如何通过微信审核？​

请参考 小程序深度合成算法资质指南，按步骤完成算法备案和类目审核。

定价与计费​

云开发 AI 能力定价如何？​

免费版和个人版套餐的用户，可以使用大模型对话能力以及Agent的人设、开场白、问题建议、知识库、数据模型和联网搜索等能力。

团队版及以上的用户，在上述功能的基础上，还可以使用高级能力，如MCP、语音功能、文件上传、多会话模式等。

100万token的限时活动​

云开发限时活动，为每个环境赠送100万token，6个月内有效，截止时间到2025年12月31日。具体细则如下：

  • 在2025年2月14日之前创建的环境，赠送资源包自2025年2月14日生效，到2025年8月14日失效。
  • 在2025年2月14日～2025年12月31日创建的环境，赠送资包自环境创建之日起生效，6个月后失效。

赠送token耗尽之后如何收费?​

赠送 token 即将用完或者已耗尽，平台不会在套餐之外单独收费，后续调用改为从云开发套餐抵扣。能否正常抵扣，取决于当前环境的套餐类型：

当前套餐赠送 token 耗尽后处理方式
资源点套餐自动转为消耗套餐内的资源点，按各模型的 Token 用量折算，资源点充足即可继续使用无需改代码，建议把 provider 切换为 cloudbase
非资源点套餐（如配额制套餐）套餐不支持抵扣大模型 Token 用量，调用会直接失败前往 云开发控制台 → 套餐管理 切换为资源点套餐，切换后即可从套餐抵扣
推荐做法：切换为资源点套餐
  1. 进入 云开发控制台 → 套餐管理，将环境切换为资源点套餐。
  2. 调用时使用 cloudbase provider（ai.createModel("cloudbase")），免费额度用尽后会自动从套餐资源点抵扣，无需配置 API Key。
  3. 切换后还可直接使用 deepseek-v4-flash、glm-5.2、kimi-k2.6、minimax-m3 等更多模型。

详细说明见 接入大模型 - 资源点套餐。

备注
  • 使用 hunyuan-v3 provider 时，免费额度耗尽后不会转为套餐抵扣，会直接报错；希望耗尽后继续按量使用，请改用 cloudbase provider。两者的完整差异见 小程序成长计划使用指南。
  • 如需调用第三方模型，仍可在 AI+ 模块配置自定义模型，此时用量由模型提供商侧计费，详见 接入自定义模型。

知识库相关​

点击查看 知识库常见问题

测试与故障排查​

常见错误码​

调用 AI 大模型 API 时可能遇到以下错误：

状态码说明解决方案
401认证失败检查 API Key 是否正确
403权限不足检查环境配置和模型权限
429请求过多降低请求频率，或参考 token 配额不足
500服务器错误稍后重试

错误响应示例：

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

小程序发布之后，为什么 AI 不回复消息？​

可能原因及解决方法​
  1. Agent UI 参数配置：检查是否传入正确的 botId 或大模型配置。
  2. 微搭可视化开发授权认证：确保小程序使用扫码授权方式，全托管认证方式暂不支持。
  3. 小程序 IDE 基础库版本：选择 3.7.7 及以上版本。
  4. 用户微信客户端版本：需高于 8.0.55，低于此版本建议升级微信。
进一步操作​
  • 核对以上各项设置，确保配置正确无误。
  • 若问题依旧存在，建议查阅官方文档或联系技术支持获取帮助。

如何优化 AI 对话的输出效果？​

可能原因及解决方法：

1. 知识库内容质量问题​

知识库内容的数量和质量是影响 AI 对话输出效果的重要因素，如果知识库内容数量较少、质量较差，可能导致 AI 对话输出效果较差。建议在知识库中添加高质量的内容，如官方文档、常见问题、FAQ 等。

2. 提示词的配置​

Agent 的提示词配置会影响 AI 对话的输出效果，如果提示词配置不当，可能导致 AI 对话输出效果较差。

可以采用提示词工程的一些通用技巧来优化提示词，参考提示词工程

可采用的方法包括：

  1. 使用清晰、明确、简洁的提示词来引导 AI 生成答案，避免使用过于复杂或模糊的提示词。
  2. 结构化 Prompt 模板（CO-STAR 框架）​
  3. 针对一些必须要遵循的要求，可以通过增加强调词来引导 AI，例如加入 特别重要 等字眼来要求 AI 遵循要求。
  4. 为 AI 提供输出的样例，例如在提示词中加入 示例： 等字眼，引导 AI 生成符合要求的答案。
  5. 对于许多复杂任务，可以设置步骤，例如"第一步：xxx，第二步：xxx，第三步：xxx"等。
  6. 引导模型思考，例如在提示词中加入 请思考 等字眼，引导 AI 思考后再生成答案。
  7. 提示词的迭代，针对现网回答的效果进行评估和迭代提示词。

流式输出过程突然中断的原因是什么？​

如果 Agent 出现了思考或者回答中途会停止的问题，目前主要出现在当思考内容较长或者回答内容较长的情况，在请求大模型时，提示词的简单程度、网络速度等多重因素可能都会让请求时长增加。

可能原因：客户端请求超时，可以修改客户端网络超时配置

小程序端全局超时配置​

可以在微信小程序中的 app.json 中配置全局超时时间，可以根据小程序的实际情况进行配置，建议配置为 10 分钟以内

{
  "networkTimeout": {
    "request": 600000
  }
}

参考链接：https://developers.weixin.qq.com/miniprogram/dev/reference/configuration/app.html#networkTimeout

web 端超时配置​

cloudbase-js-sdk 默认设置了超时时间为 15 秒，当请求超时时，会主动取消请求。用户可以在 cloudbase.init 时自定义超时时间。

import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({
  env: "your-env", // 需替换为实际使用环境 id
  timeout: 600000, // 设置超时时间为 10 分钟
});
const auth = app.auth();
await auth.signInAnonymously(); // 或者使用其他登录方式
const ai = app.ai(); // 后续就可以按常规方式调用 ai 能力了

Agent UI 区块组件引入后小程序包大小超了怎么办​

在小程序源码中使用推荐使用源码组件，具体参考 指引三：使用云开发 AI 对话组件，快速接入 AI 对话，或者参考下面的链接来使用子包引入。

第 1 步：使用子包形式引入​

  1. 下载组件代码包：组件下载地址。

  2. 解压并放置：将组件包放入小程序项目根目录下的 components/agent-ui 目录。

  3. 配置 app.json：

    {
      "lazyCodeLoading": "requiredComponents",
      "subpackages": [
        {
          "root": "components/agent-ui",
          "name": "agent-ui",
          "pages": []
        }
      ]
    }

  4. 配置 project.config.json：

    {
      "setting": {
        "ignoreDevUnusedFiles": true,
        "ignoreUploadUnusedFiles": true
      }
    }
第 2 步：初始化对话组件​

  1. 修改 ./components/agent-ui/index.js：

    import * as sdk from "@cloudbase/weda-client";
    sdk.init({
      envID: "<云开发环境ID>",
    });

  2. 在组件头部添加引用：在 ./components/agent-ui/dist/Agent-UI/index.js 中添加 import '../../index'，确保组件加载时立即初始化 SDK。

通过以上步骤，可以有效减小小程序主包的大小，并确保 Agent UI 组件的正确初始化和使用。

为何向订阅号发送消息后会收到“思考中，请回复‘继续’”的回应？​

对于订阅号或者未认证的服务号，只能在 15 秒内进行被动回复。若消息处理时间超出这一时限，系统便会自动发送“思考中，请回复‘继续’”的提示。

已经认证的服务号不受此限制。

可以尝试：

  • 手动回复“继续”：促使系统继续完成回复流程。
  • 优化智能回复设置：调整智能体的回复策略，确保回复内容简洁且能在规定时间内完成。

优化建议：

  1. 在提示词增加如下设定,可以显著提升回复速度，测试时建议换一个微信号测试公众号的回复效果（更改提示词，历史回复可能会影响模型的输出）
- 智能体以极简风格回应问题。
- 简化复杂问题的回答，提炼核心信息。
- 严格限制回复内容的长度和相关性，避免冗余。
- 不要输出 markdown 格式，直接输出纯文本
  1. 如果使用深度思考模型（如 DeepSeek R1），响应的时间会较慢，可以考虑使用混元模型或者 DeepSeek V3 模型。
  2. 如果希望更好的体验，可以考虑使用公众号个性化菜单嵌入 H5/小程序的形式，支持更好的对话体验

在流式调用时，如何才能知道流式传输结束了？​

for await 代码块后的代码在流式传输之后才会执行，所以只要在for await 代码块后做流式调用结束相关的通知/设定标识的操作即可。

const hy = ai.createModel("cloudbase"); // 创建模型
const res = await hy.streamText({
  model: "hy3",
  messages: [{ role: "user", content: "你好，请你介绍一下李白" }],
});

for await (let str of res.textStream) {
  console.log(str);
}
console.log("流式传输结束啦"); // 流式传输结束后才会执行这里的代码！

Agent UI 源码版本开发者工具勾选“上传时进行代码保护“会报错?​

开启此选项，开发者工具会尝试对项目代码进行保护，主要是对文件进行扁平化处理并替换 require 引用的文件名

由于其中有动态引用的情况，如 var a = 'somefile.js'; require(a);不适合使用此功能，所以建议关闭此选项

技术细节​

在小程序中使用 AI+，我该用微信小程序基础库还是 AI SDK？​

AI SDK 和微信小程序基础库提供的 AI 能力是相同的。

AI SDK 是云开发提供的多端 SDK，在多个平台都有一致的使用体验。如果您有一码多端的需求，可以选用 AI SDK。

然而在小程序上使用 AI SDK 会受到一定的限制：

  1. 小程序包体积有限制，引入 AI SDK 会增加一定的包体积
  2. 小程序需要配置服务器域名，配置完成后 AI SDK 才能进行请求

微信小程序基础库内置了完整的云开发 AI 能力，不占用包体积，也无需配置服务器域名。对于专注于小程序的开发者们，使用微信小程序基础库是一个好的选择。在不用安装任何外部包的情况下，也能完整地访问到云开发提供的 AI+ 能力。

微信小程序基础库和 AI SDK 在使用方法上有一定的区分，请注意阅读文档。