AI创客项目开发教程 -AID101-1-2-03 – User Role详解

导航栏：首页 / AI教程目录 / AI创客项目开发教程目录 / 第1篇基础知识篇 / AID101-1-2-03 – User Role详解

本节内容简介

本节将详细讲解 user_role.ino 程序的工作原理。这个程序演示了如何在 ESP32 开发板上通过 User Role（用户角色）向 AI 发送用户的问题和指令。通过本节课程，您将理解 System Role 与 User Role 的区别，以及如何在实际应用中配合使用两者。

User Role（用户角色）详解

什么是 User Role？

User Role（用户角色）用于承载用户的输入内容，是与 AI 对话的主要载体。在调用 AI 平台 API 时，User Role 发送的是用户的具体问题、指令或需要 AI 处理的信息。

与 System Role 定义 AI 的行为模式不同，User Role 关注的是”用户想要什么”。如果说 System Role 是给 AI 设定一个人设和规则，那么 User Role 就是用户向 AI 提出的具体问题或指令。

User Role 的核心特点：

📝 内容承载：承载用户的具体问题、指令或信息
🎯 目标导向：明确告诉 AI 用户想要什么
🔄 动态变化：每轮对话都可以发送不同的内容
📋 格式要求：可以包含格式化输出要求

User Role 的典型应用：

简单问答：用户直接提问，AI 回答
格式化指令：用户要求 AI 按特定格式输出
多轮对话：每轮对话中用户发送新消息

User Role 与 System Role 的区别

特性	System Role	User Role
定义者	开发者/系统管理员	用户
作用	设定 AI 的行为规则	发送用户的问题或指令
变化频率	通常固定不变	每次对话都可能变化
内容类型	AI 的身份、风格、格式要求	问题、指令、信息
示例	“你是张飞，说话要粗犷”	“请解释什么是人工智能”

简单理解：

System Role = 给 AI 设定”人设”和”规则”
User Role = 用户对 AI 说的话

两者配合使用：System Role 告诉 AI”你是谁、怎么回答”，User Role 告诉 AI”用户想问什么”。

本节代码 – User Role 演示示例

注意

本程序需要配合my_info.h代码使用，否则程序将无法正常编译。
请点击以下链接前往该代码页面，复制下载该代码：

http://ai.taichi-maker.com/index.php/homepage/ai-tutorial-index/ai-maker-project-tutorial-index/my_info_h-code-description/

/*
 * ESP32 AI平台 User Role 演示示例
 *
 * 功能描述：
 * 本程序演示如何在 ESP32 开发板上通过 User Role（用户角色）向 AI 发送用户的问题和指令。
 * 与 System Role 定义 AI 的行为模式不同，User Role 承载的是用户的具体输入内容。
 * 通过本示例，您将理解 System Role 与 User Role 的区别，以及如何在实际应用中配合使用两者。
 *
 * 本示例特点：
 * 1. User Role 演示：通过 User Role 发送用户的具体问题和指令
 * 2. 配合 System Role 使用：展示如何同时使用 System Role 和 User Role
 * 3. 多种 User Role 示例：展示 User Role 在不同场景下的应用
 *
 * 作者：Taichi-Maker
 * 作者官网：http://ai.taichi-maker.com
 * 创建日期：2026年03月23日
 * 版本：1.0.2
 *
 * 硬件要求：
 * - 支持 Wi-Fi 的 ESP32 开发板（推荐使用 ESP32-S3-DevKitC-1，因其性能更好、内存更大）
 *
 * 配置说明：
 * 1. 在 my_info.h 中填写 Wi-Fi 名称（ssid）和密码（password）
 * 2. 在 my_info.h 中设置 ai_api_key（从 AI 平台获取的 API 密钥）
 *
 * 使用方法：
 * 将本程序上传至 ESP32 后，打开串口监视器（波特率设置为 115200），
 * 程序会自动连接 Wi-Fi 并向 AI 平台发送一次请求，随后打印完整的 HTTP 响应内容。
 *
 * 注意事项：
 * - 本例使用 client.setInsecure() 跳过了 SSL 证书验证，仅适用于测试环境；
 *   在生产环境中应使用有效证书以确保通信安全。
 * - 请求仅在 setup() 中执行一次，loop() 为空，不会重复发送。
 *
 * 兼容性说明：
 * 本程序已在 ESP32-S3-DevKitC-1 开发板上测试通过。
 *
 * 许可证：MIT License
 *
 * 程序源：
 * 本程序源自太极创客团队精心开发的《AI创客项目开发教程》。该教程专为热爱科技创新、热衷于动手实践
 * 创客爱好者与初学者量身打造，是一套完全免费、开源且注重实战的AIoT（人工智能物联网）入门学习资源。
 *
 * 通过本教程，您可以系统地掌握从项目构思、方案设计、软硬件选型，到实际搭建、系统集成与调试优化的
 * 完整开发流程。
 * 
 * 您可以通过以下链接获得更多关于本教程的详细信息：
 * http://ai.taichi-maker.com/index.php/homepage/ai-tutorial/
 */

#include <WiFi.h>
#include <WiFiClientSecure.h>
#include <HTTPClient.h>
#include "my_info.h"

/*
 * -------------- User Role 详解 --------------
 *
 * User Role（用户角色）用于承载用户的输入内容，是与 AI 对话的主要载体。
 * 与 System Role 定义 AI 的行为模式不同，User Role 发送的是用户的具体问题、指令或信息。
 *
 * User Role 的典型应用场景：
 *
 * 1. 简单问答：
 *    用户直接提问，AI 回答
 *    {
 *      "role": "user",
 *      "content": "什么是人工智能？"
 *    }
 *
 * 2. 格式化指令：
 *    用户要求 AI 按特定格式输出
 *    {
 *      "role": "user",
 *      "content": "请用 JSON 格式输出以下产品的信息：名称、价格、库存"
 *    }
 *
 *
 * 提示：
 * 1. User Role 的内容就是用户想要 AI 回答的问题或执行的指令
 * 2. User Role 可以包含格式化要求，指定 AI 的输出结构
 * 
 */
const char* ai_payload = R"rawliteral({
  "model": "qwen-flash",
  "messages": [
    {
      "role": "system",
      "content": "你是一个智能助手。请用简洁明了的语言回答问题。"
    },
    {
      "role": "user",
      "content": "请将下面的文字翻译成英文：你好，世界！"
    }
  ],
  "temperature": 0.7
})rawliteral";

// 创建一个安全的 Wi-Fi 客户端（用于 HTTPS 连接）
WiFiClientSecure client;

// 创建 HTTP 客户端对象，用于发送请求
HTTPClient https;

void setup() {
  // 初始化串口通信，波特率为 115200
  Serial.begin(115200);
  delay(1000); // 短暂等待串口稳定

  // 开始连接 Wi-Fi
  Serial.print("Connecting WiFi");
  WiFi.begin(ssid, password);

  // 循环等待直到成功连接
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }

  // 成功连接后换行
  Serial.println();

  // 【重要】跳过 SSL 证书验证（仅用于开发测试！）
  // 在真实产品中应加载有效证书以防止中间人攻击
  client.setInsecure();

  // 设置SSL连接超时时间
  client.setTimeout(15); // 15秒超时

  Serial.println();
  Serial.println("---------- AI Platform Config ----------");
  Serial.print("AI Platform API Endpoint: ");
  Serial.print(ai_host);
  Serial.println(ai_endpoint);
  Serial.println();

  // 调用函数，向 AI 平台发送请求
  callAIPlatform();
}

// 主循环留空，因为本例只需发送一次请求
void loop() {
  // 空
}

/*
 * -------------- 向 AI 平台发送 HTTPS 请求的核心函数 --------------
 */
void callAIPlatform() {
  Serial.println("\n>>> Calling AI Platform API...");

  // 打印请求体大小，用于调试
  Serial.printf("Request payload size: %d bytes\n", strlen(ai_payload));

  // 构造 Authorization 请求头：格式为 "Bearer <your-api-key>"
  String auth = "Bearer ";
  auth += ai_api_key;

  // 初始化 HTTPS 连接（使用 client、主机名、端口、API 路径）
  if (https.begin(client, ai_host, ai_port, ai_endpoint)) {

    // 设置超时时间（毫秒）- 增加超时时间以处理更复杂的请求
    https.setTimeout(20000); // 20秒超时
    https.setConnectTimeout(10000); // 10秒连接超时

    Serial.println("HTTPS connection initialized, sending request...");

    // 添加必要的 HTTP 请求头
    https.addHeader("Content-Type", "application/json");
    https.addHeader("Authorization", auth);

    // 发送 POST 请求，并获取 HTTP 状态码
    int httpCode = https.POST(ai_payload);

    if (httpCode > 0) {
      // 打印 HTTP 响应状态码（如 200 表示成功）
      Serial.printf("HTTP Response code: %d\n", httpCode);

      // 如果响应成功（HTTP 200 OK）
      if (httpCode == HTTP_CODE_OK) {
        // 获取完整的响应字符串
        String resp = https.getString();
        Serial.println("----- Response -----");
        Serial.println(resp);  // 打印 AI 返回的完整 JSON（含模型生成的回答）
        Serial.println("----- End -----");
      }
    } else {
      // 打印 HTTP 错误信息（如连接失败、超时等）
      Serial.printf("HTTP error: %s\n", https.errorToString(httpCode).c_str());
      Serial.printf("Error code: %d\n", httpCode);
    }

    // 结束本次 HTTP 会话，释放资源
    https.end();
  } else {
    // 如果无法建立 HTTPS 连接，打印错误提示
    Serial.println("Unable to connect to server");
  }
}

/*
----- AI平台响应示例 -----
请注意，由于不同AI平台的响应信息或多或少的存在一定差异，以下响应示例仅供学习参考。
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Hello, World!"
      },
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null
    }
  ],
  "object": "chat.completion",
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 4,
    "total_tokens": 36,
    "prompt_tokens_details": {
      "cached_tokens": 0
    }
  },
  "created": 1767370001,
  "system_fingerprint": null,
  "model": "qwen-flash",
  "id": "chatcmpl-12345678-1234-1234-1234-123456789012"
}
*/

/*
 * ESP32 AI平台 User Role 演示示例
 *
 * 功能描述：
 * 本程序演示如何在 ESP32 开发板上通过 User Role（用户角色）向 AI 发送用户的问题和指令。
 * 与 System Role 定义 AI 的行为模式不同，User Role 承载的是用户的具体输入内容。
 * 通过本示例，您将理解 System Role 与 User Role 的区别，以及如何在实际应用中配合使用两者。
 *
 * 本示例特点：
 * 1. User Role 演示：通过 User Role 发送用户的具体问题和指令
 * 2. 配合 System Role 使用：展示如何同时使用 System Role 和 User Role
 * 3. 多种 User Role 示例：展示 User Role 在不同场景下的应用
 *
 * 作者：Taichi-Maker
 * 作者官网：http://ai.taichi-maker.com
 * 创建日期：2026年03月23日
 * 版本：1.0.2
 *
 * 硬件要求：
 * - 支持 Wi-Fi 的 ESP32 开发板（推荐使用 ESP32-S3-DevKitC-1，因其性能更好、内存更大）
 *
 * 配置说明：
 * 1. 在 my_info.h 中填写 Wi-Fi 名称（ssid）和密码（password）
 * 2. 在 my_info.h 中设置 ai_api_key（从 AI 平台获取的 API 密钥）
 *
 * 使用方法：
 * 将本程序上传至 ESP32 后，打开串口监视器（波特率设置为 115200），
 * 程序会自动连接 Wi-Fi 并向 AI 平台发送一次请求，随后打印完整的 HTTP 响应内容。
 *
 * 注意事项：
 * - 本例使用 client.setInsecure() 跳过了 SSL 证书验证，仅适用于测试环境；
 *   在生产环境中应使用有效证书以确保通信安全。
 * - 请求仅在 setup() 中执行一次，loop() 为空，不会重复发送。
 *
 * 兼容性说明：
 * 本程序已在 ESP32-S3-DevKitC-1 开发板上测试通过。
 *
 * 许可证：MIT License
 *
 * 程序源：
 * 本程序源自太极创客团队精心开发的《AI创客项目开发教程》。该教程专为热爱科技创新、热衷于动手实践
 * 创客爱好者与初学者量身打造，是一套完全免费、开源且注重实战的AIoT（人工智能物联网）入门学习资源。
 *
 * 通过本教程，您可以系统地掌握从项目构思、方案设计、软硬件选型，到实际搭建、系统集成与调试优化的
 * 完整开发流程。
 * 
 * 您可以通过以下链接获得更多关于本教程的详细信息：
 * http://ai.taichi-maker.com/index.php/homepage/ai-tutorial/
 */

#include <WiFi.h>
#include <WiFiClientSecure.h>
#include <HTTPClient.h>
#include "my_info.h"

/*
 * -------------- User Role 详解 --------------
 *
 * User Role（用户角色）用于承载用户的输入内容，是与 AI 对话的主要载体。
 * 与 System Role 定义 AI 的行为模式不同，User Role 发送的是用户的具体问题、指令或信息。
 *
 * User Role 的典型应用场景：
 *
 * 1. 简单问答：
 *    用户直接提问，AI 回答
 *    {
 *      "role": "user",
 *      "content": "什么是人工智能？"
 *    }
 *
 * 2. 格式化指令：
 *    用户要求 AI 按特定格式输出
 *    {
 *      "role": "user",
 *      "content": "请用 JSON 格式输出以下产品的信息：名称、价格、库存"
 *    }
 *
 *
 * 提示：
 * 1. User Role 的内容就是用户想要 AI 回答的问题或执行的指令
 * 2. User Role 可以包含格式化要求，指定 AI 的输出结构
 * 
 */
const char* ai_payload = R"rawliteral({
  "model": "qwen-flash",
  "messages": [
    {
      "role": "system",
      "content": "你是一个智能助手。请用简洁明了的语言回答问题。"
    },
    {
      "role": "user",
      "content": "请将下面的文字翻译成英文：你好，世界！"
    }
  ],
  "temperature": 0.7
})rawliteral";

// 创建一个安全的 Wi-Fi 客户端（用于 HTTPS 连接）
WiFiClientSecure client;

// 创建 HTTP 客户端对象，用于发送请求
HTTPClient https;

void setup() {
  // 初始化串口通信，波特率为 115200
  Serial.begin(115200);
  delay(1000); // 短暂等待串口稳定

  // 开始连接 Wi-Fi
  Serial.print("Connecting WiFi");
  WiFi.begin(ssid, password);

  // 循环等待直到成功连接
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }

  // 成功连接后换行
  Serial.println();

  // 【重要】跳过 SSL 证书验证（仅用于开发测试！）
  // 在真实产品中应加载有效证书以防止中间人攻击
  client.setInsecure();

  // 设置SSL连接超时时间
  client.setTimeout(15); // 15秒超时

  Serial.println();
  Serial.println("---------- AI Platform Config ----------");
  Serial.print("AI Platform API Endpoint: ");
  Serial.print(ai_host);
  Serial.println(ai_endpoint);
  Serial.println();

  // 调用函数，向 AI 平台发送请求
  callAIPlatform();
}

// 主循环留空，因为本例只需发送一次请求
void loop() {
  // 空
}

/*
 * -------------- 向 AI 平台发送 HTTPS 请求的核心函数 --------------
 */
void callAIPlatform() {
  Serial.println("\n>>> Calling AI Platform API...");

  // 打印请求体大小，用于调试
  Serial.printf("Request payload size: %d bytes\n", strlen(ai_payload));

  // 构造 Authorization 请求头：格式为 "Bearer <your-api-key>"
  String auth = "Bearer ";
  auth += ai_api_key;

  // 初始化 HTTPS 连接（使用 client、主机名、端口、API 路径）
  if (https.begin(client, ai_host, ai_port, ai_endpoint)) {

    // 设置超时时间（毫秒）- 增加超时时间以处理更复杂的请求
    https.setTimeout(20000); // 20秒超时
    https.setConnectTimeout(10000); // 10秒连接超时

    Serial.println("HTTPS connection initialized, sending request...");

    // 添加必要的 HTTP 请求头
    https.addHeader("Content-Type", "application/json");
    https.addHeader("Authorization", auth);

    // 发送 POST 请求，并获取 HTTP 状态码
    int httpCode = https.POST(ai_payload);

    if (httpCode > 0) {
      // 打印 HTTP 响应状态码（如 200 表示成功）
      Serial.printf("HTTP Response code: %d\n", httpCode);

      // 如果响应成功（HTTP 200 OK）
      if (httpCode == HTTP_CODE_OK) {
        // 获取完整的响应字符串
        String resp = https.getString();
        Serial.println("----- Response -----");
        Serial.println(resp);  // 打印 AI 返回的完整 JSON（含模型生成的回答）
        Serial.println("----- End -----");
      }
    } else {
      // 打印 HTTP 错误信息（如连接失败、超时等）
      Serial.printf("HTTP error: %s\n", https.errorToString(httpCode).c_str());
      Serial.printf("Error code: %d\n", httpCode);
    }

    // 结束本次 HTTP 会话，释放资源
    https.end();
  } else {
    // 如果无法建立 HTTPS 连接，打印错误提示
    Serial.println("Unable to connect to server");
  }
}

/*
----- AI平台响应示例 -----
请注意，由于不同AI平台的响应信息或多或少的存在一定差异，以下响应示例仅供学习参考。
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Hello, World!"
      },
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null
    }
  ],
  "object": "chat.completion",
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 4,
    "total_tokens": 36,
    "prompt_tokens_details": {
      "cached_tokens": 0
    }
  },
  "created": 1767370001,
  "system_fingerprint": null,
  "model": "qwen-flash",
  "id": "chatcmpl-12345678-1234-1234-1234-123456789012"
}
*/

代码详解

以上代码是使用了本章第一节课的示例程序，并且对其进行了简单调整修改而来。

相比本章第一节课的示例程序，本程序主要修改了以下几部分：

修改1：System Role 内容更加简单

本节课程的示例程序将System Role修改为更加通用的内容。这样可以更加突出显示出User Role的作用。

{
  "role": "system",
  "content": "你是一个智能助手。请用简洁明了的语言回答问题。"
}

{
  "role": "system",
  "content": "你是一个智能助手。请用简洁明了的语言回答问题。"
}

修改2：User Role 内容更加具体

本节课程的示例程序展示了更加丰富多样的 User Role 用法，包括翻译请求、格式化输出要求等不同场景。

// System Role 示例中的 User Role
{
  "role": "user",
  "content": "请解释一下什么是人工智能大语言模型"
}

// 本程序中的 User Role（翻译请求）
{
  "role": "user",
  "content": "请将下面的文字翻译成英文：你好，世界！"
}

// System Role 示例中的 User Role
{
  "role": "user",
  "content": "请解释一下什么是人工智能大语言模型"
}

// 本程序中的 User Role（翻译请求）
{
  "role": "user",
  "content": "请将下面的文字翻译成英文：你好，世界！"
}

本程序中的关键代码解析

关键代码1：User Role 定义

{
  "role": "user",
  "content": "请将下面的文字翻译成英文：你好，世界！"
}

{
  "role": "user",
  "content": "请将下面的文字翻译成英文：你好，世界！"
}

这段代码在做什么？

这是定义 User Role 的消息结构，包含角色标识和内容。

具体完成了什么任务？

"role": "user"：标识这是用户发送的消息
"content": "请将下面的文字翻译成英文：你好，世界！"：用户的具体指令

为什么这样做？

User Role 用于承载用户的输入内容
这里用户请求翻译服务，所以发送了翻译请求

关键代码2：完整的消息结构

"messages": [
  {
    "role": "system",
    "content": "你是一个智能助手。请用简洁明了的语言回答问题。"
  },
  {
    "role": "user",
    "content": "请将下面的文字翻译成英文：你好，世界！"
  }
]

"messages": [
  {
    "role": "system",
    "content": "你是一个智能助手。请用简洁明了的语言回答问题。"
  },
  {
    "role": "user",
    "content": "请将下面的文字翻译成英文：你好，世界！"
  }
]

这段代码在做什么？ 这是完整的 messages 数组，包含 System Role 和 User Role。

具体完成了什么任务？

System Role 设定了 AI 的行为模式（简洁明了回答）
User Role 发送了具体的翻译请求
两者配合，AI 会按照”简洁明了”的风格完成翻译
- System Role 和 User Role 配合使用
- System Role 定义”怎么回答”，User Role 定义”问什么”

提示词工程简介

什么是提示词工程？

提示词工程（Prompt Engineering）是指通过精心设计输入给 AI 的提示词（即 User Role 中的内容），来获得更准确、更有用的输出的技术。在与 AI 对话时，同样的问题，不同的提问方式往往会得到截然不同的回答。

为什么提示词工程很重要？

好的提示词可以让 AI 准确理解用户意图
可以引导 AI 产生更符合预期的输出
可以提高 AI 的工作效率，减少无效交互

提示词工程的核心原则

原则1：清晰具体

模糊的问题会导致模糊的回答。将问题具体化，AI 就能给出更精确的答案。

❌ 不好的提示词："帮我写一个判断闰年的函数代码"
✅ 好的提示词："用 C++ 写一个函数，判断一个年份是否是闰年"

❌ 不好的提示词："帮我写一个判断闰年的函数代码"
✅ 好的提示词："用 C++ 写一个函数，判断一个年份是否是闰年"

原则2：提供背景信息

给 AI 足够的背景信息，它就能理解你的具体需求，给出更贴切的回答。

❌ 不好的提示词："推荐几本编程书"
✅ 好的提示词："我是一个编程初学者，刚学完 C++ 基础，请推荐三本适合的进阶书籍"

❌ 不好的提示词："推荐几本编程书"
✅ 好的提示词："我是一个编程初学者，刚学完 C++ 基础，请推荐三本适合的进阶书籍"

原则3：明确输出格式

如果你需要特定格式的输出，一定要在提示词中明确说明。

❌ 不好的提示词："告诉我怎么处理这个 bug"
✅ 好的提示词："告诉我怎么处理这个 bug，并且请按以下格式回答：1. 问题原因 2. 解决方案 3. 预防措施"

❌ 不好的提示词："告诉我怎么处理这个 bug"
✅ 好的提示词："告诉我怎么处理这个 bug，并且请按以下格式回答：1. 问题原因 2. 解决方案 3. 预防措施"

原则4：分步骤处理复杂任务

对于复杂问题，将其分解成多个步骤，让 AI 逐步完成。

❌ 不好的提示词："解释量子计算并用 Python 实现"
✅ 好的提示词："请先解释量子计算的基本原理，然后使用一个简单的Python代码示例向我演示量子计算"

❌ 不好的提示词："解释量子计算并用 Python 实现"
✅ 好的提示词："请先解释量子计算的基本原理，然后使用一个简单的Python代码示例向我演示量子计算"

User Role 的使用注意事项

注意事项1：内容长度限制

问题： User Role 的内容是否有限制？

解答：

是的，有 token 数量限制（取决于模型）
User Role + System Role + 历史信息的总 token 不能超过模型上限
如果内容过长，可能需要精简或分段发送

建议：

保持问题简洁明了
避免重复的上下文信息
如果超长，考虑只保留关键的上下文

注意事项2：User Role 与 System Role 的配合

问题： 如何正确配合使用 User Role 和 System Role？

解答：

System Role 设置 AI 的角色定位和回答风格
User Role 发送用户的具体问题
两者相辅相成，共同构成完整的对话

总结

User Role 的核心价值

内容承载：承载用户的具体问题、指令或信息
目标导向：明确告诉 AI 用户想要什么
灵活性高：可用于各种场景的问答和任务
配合 System Role：与 System Role 配合，构建完整的对话系统

User Role 的编写要点

问题具体明确：避免模糊的问题描述
提供必要背景信息：帮助 AI 更好地理解问题
明确输出格式：如果需要特定格式，要明确说明
分步骤提问：复杂问题可以分步进行