AI创客项目开发教程 -AID101-1-2-01 – 使用ESP32调用AI大模型API的基本操作

导航栏：首页 / AI教程目录 / AI创客项目开发教程目录 / 第1篇基础知识篇 / AID101-1-2-01 – 使用ESP32调用AI大模型API的基本操作

本节内容简介

本节将详细讲解 simple_request.ino 程序的工作原理。这个程序的功能是：让 ESP32 开发板连接 Wi-Fi 后，向 AI 平台发送请求，并获取 AI 的回答。

在本系列教程里，我们将使用阿里云百炼平台作为示例平台。

整个程序可以分为四个阶段：初始化与准备、系统启动、发送AI请求和主循环。接下来，我们将逐步分析每个阶段的具体工作

本节代码 – ESP32 AI平台调用简单示例

注意

本程序需要配合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平台调用 简单示例
 * 
 * 功能描述：
 * 本程序演示如何在 ESP32（特别是 ESP32-S3）开发板上，通过 HTTPS 协议向阿里云百炼大模型服务平台
 * 发送一个标准的 OpenAI 兼容格式的请求，调用 Qwen/Qwen3-8B 大语言模型，并在串口监视器中打印返回结果。
 * 
 * 作者：Taichi-Maker
 * 作者官网：http://ai.taichi-maker.com
 * 创建日期：2026年03月20日
 * 版本：1.0.1
 * 
 * 硬件要求：
 * - 支持 Wi-Fi 的 ESP32 开发板
 *   推荐使用 ESP32-S3-DevKitC-1
 * 
 * 配置说明：
 * 1. 在 my_info.h 文件中填写您的 Wi-Fi 名称（ssid）和密码（password）。
 * 2. 在 my_info.h 文件中将 ai_api_key 替换为您从 AI 平台获取的有效 API 密钥（切勿泄露！）。
 * 3. 确保开发板已正确连接到电脑，并选择正确的开发板型号与端口。
 * 
 * 使用方法：
 * 将本程序上传至 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"

/* 
 * -------------- JSON 请求体 --------------
 * 
 * 此处使用 C++11 的原始字符串字面量（Raw String Literal）语法 R"rawliteral(...)rawliteral"
 * 来定义一个多行 JSON 字符串，避免手动转义双引号和换行符。
 * 
 * 该 JSON 符合 OpenAI API 兼容格式，包含以下关键字段：
 * - model: 指定要调用的 AI 模型名称（此处为 Qwen/Qwen3-8B）
 * - messages: 对话历史，由系统角色（system）和用户输入（user）组成
 * - temperature: 控制生成文本的随机性（0.7 表示适度创造性）
 * - max_tokens: 限制模型最多生成的 token 数量（150 个）
 */
const char* ai_payload = R"rawliteral({
  "model": "qwen-flash",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Hi. Who are you?"
    }
  ],
  "temperature": 0.7,
  "max_tokens": 150
})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();
  
  callAIPlatform();  // 发送AI请求
}

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

/* 
 * -------------- 向 AI 平台发送 HTTPS 请求的核心函数 --------------
 * 
 * 该函数完成以下步骤：
 * 1. 构造完整的 HTTPS 请求 URL（基于 my_info.h 中定义的主机、端口和路径）
 * 2. 设置请求头：Content-Type 为 application/json，Authorization 为 Bearer + API 密钥
 * 3. 发送 POST 请求，携带上述 JSON 请求体
 * 4. 接收并打印 HTTP 响应状态码和响应内容
 */
void callAIPlatform() {
  Serial.println("\n>>> Calling AI Platform API...");

  // 构造 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");
  }
}

/*
 * ========================================================================
 * 【附录】本程序实际发送的 HTTP 请求内容（供参考）
 * ========================================================================
 * 
 * 假设 my_info.h 中定义如下（仅为示例）：
 *   const char* ai_host = "dashscope.aliyuncs.com";
 *   const uint16_t ai_port = 443;
 *   const char* ai_endpoint = "/compatible-mode/v1/chat/completions";
 *   const char* ai_api_key = "sk-xxxxxxxxxxxxxxxxxxxxxxxx";
 * 
 * 则程序实际发出的完整 HTTP 请求如下：
 * 
 * POST /compatible-mode/v1/chat/completions HTTP/1.1
 * Host: dashscope.aliyuncs.com
 * Content-Type: application/json
 * Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx
 * Content-Length: [自动计算]
 * 
 * {
 *   "model": "Qwen/Qwen3-8B",
 *   "messages": [
 *     {
 *       "role": "system",
 *       "content": "You are a helpful assistant."
 *     },
 *     {
 *       "role": "user",
 *       "content": "Hi. Who are you?"
 *     }
 *   ],
 *   "temperature": 0.7,
 *   "max_tokens": 150
 * }
 * 
 * 说明：
 * - 这是一个标准的 OpenAI 兼容 API 调用格式。
 * - 服务器收到后会使用指定模型生成回答，并以 JSON 格式返回（包含 usage、choices 等字段）。
 * - ESP32 通过 HTTPS 安全地传输此请求，并打印返回结果供调试。
 * ========================================================================
 */

/* 
 * ESP32 AI平台调用 简单示例
 * 
 * 功能描述：
 * 本程序演示如何在 ESP32（特别是 ESP32-S3）开发板上，通过 HTTPS 协议向阿里云百炼大模型服务平台
 * 发送一个标准的 OpenAI 兼容格式的请求，调用 Qwen/Qwen3-8B 大语言模型，并在串口监视器中打印返回结果。
 * 
 * 作者：Taichi-Maker
 * 作者官网：http://ai.taichi-maker.com
 * 创建日期：2026年03月20日
 * 版本：1.0.1
 * 
 * 硬件要求：
 * - 支持 Wi-Fi 的 ESP32 开发板
 *   推荐使用 ESP32-S3-DevKitC-1
 * 
 * 配置说明：
 * 1. 在 my_info.h 文件中填写您的 Wi-Fi 名称（ssid）和密码（password）。
 * 2. 在 my_info.h 文件中将 ai_api_key 替换为您从 AI 平台获取的有效 API 密钥（切勿泄露！）。
 * 3. 确保开发板已正确连接到电脑，并选择正确的开发板型号与端口。
 * 
 * 使用方法：
 * 将本程序上传至 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"

/* 
 * -------------- JSON 请求体 --------------
 * 
 * 此处使用 C++11 的原始字符串字面量（Raw String Literal）语法 R"rawliteral(...)rawliteral"
 * 来定义一个多行 JSON 字符串，避免手动转义双引号和换行符。
 * 
 * 该 JSON 符合 OpenAI API 兼容格式，包含以下关键字段：
 * - model: 指定要调用的 AI 模型名称（此处为 Qwen/Qwen3-8B）
 * - messages: 对话历史，由系统角色（system）和用户输入（user）组成
 * - temperature: 控制生成文本的随机性（0.7 表示适度创造性）
 * - max_tokens: 限制模型最多生成的 token 数量（150 个）
 */
const char* ai_payload = R"rawliteral({
  "model": "qwen-flash",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Hi. Who are you?"
    }
  ],
  "temperature": 0.7,
  "max_tokens": 150
})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();
  
  callAIPlatform();  // 发送AI请求
}

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

/* 
 * -------------- 向 AI 平台发送 HTTPS 请求的核心函数 --------------
 * 
 * 该函数完成以下步骤：
 * 1. 构造完整的 HTTPS 请求 URL（基于 my_info.h 中定义的主机、端口和路径）
 * 2. 设置请求头：Content-Type 为 application/json，Authorization 为 Bearer + API 密钥
 * 3. 发送 POST 请求，携带上述 JSON 请求体
 * 4. 接收并打印 HTTP 响应状态码和响应内容
 */
void callAIPlatform() {
  Serial.println("\n>>> Calling AI Platform API...");

  // 构造 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");
  }
}

/*
 * ========================================================================
 * 【附录】本程序实际发送的 HTTP 请求内容（供参考）
 * ========================================================================
 * 
 * 假设 my_info.h 中定义如下（仅为示例）：
 *   const char* ai_host = "dashscope.aliyuncs.com";
 *   const uint16_t ai_port = 443;
 *   const char* ai_endpoint = "/compatible-mode/v1/chat/completions";
 *   const char* ai_api_key = "sk-xxxxxxxxxxxxxxxxxxxxxxxx";
 * 
 * 则程序实际发出的完整 HTTP 请求如下：
 * 
 * POST /compatible-mode/v1/chat/completions HTTP/1.1
 * Host: dashscope.aliyuncs.com
 * Content-Type: application/json
 * Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx
 * Content-Length: [自动计算]
 * 
 * {
 *   "model": "Qwen/Qwen3-8B",
 *   "messages": [
 *     {
 *       "role": "system",
 *       "content": "You are a helpful assistant."
 *     },
 *     {
 *       "role": "user",
 *       "content": "Hi. Who are you?"
 *     }
 *   ],
 *   "temperature": 0.7,
 *   "max_tokens": 150
 * }
 * 
 * 说明：
 * - 这是一个标准的 OpenAI 兼容 API 调用格式。
 * - 服务器收到后会使用指定模型生成回答，并以 JSON 格式返回（包含 usage、choices 等字段）。
 * - ESP32 通过 HTTPS 安全地传输此请求，并打印返回结果供调试。
 * ========================================================================
 */

代码详解

阶段一：初始化与准备

在程序正式开始运行之前，需要先做好一些准备工作。这一阶段主要完成两件事：引入必要的库文件，以及定义请求数据。

步骤1：包含必要的库 (第48-51行)

#include <WiFi.h>              // Wi-Fi连接功能
#include <WiFiClientSecure.h>  // 安全的HTTPS客户端
#include <HTTPClient.h>        // HTTP请求功能
#include "my_info.h"           // 用户配置信息（WiFi密码、API密钥等）

#include <WiFi.h>              // Wi-Fi连接功能
#include <WiFiClientSecure.h>  // 安全的HTTPS客户端
#include <HTTPClient.h>        // HTTP请求功能
#include "my_info.h"           // 用户配置信息（WiFi密码、API密钥等）

程序的开始处使用 #include 指令引入了四个库文件。这些库相当于 ESP32 的”工具包”，分别提供不同的功能：

WiFi.h：让 ESP32 能够连接无线网络
WiFiClientSecure.h：让 ESP32 能够通过加密方式（HTTPS）与服务器安全通信
HTTPClient.h：让 ESP32 能够按照 HTTP 协议发送网络请求
my_info.h：这是用户自定义的文件，用来存放 Wi-Fi 名称、密码以及 AI 平台的 API 密钥

步骤2：定义AI请求的JSON体 (第65-79行)

const char* ai_payload = R"rawliteral({
  "model": "qwen-flash",
  "messages": [...],
  "temperature": 0.7,
  "max_tokens": 150
})rawliteral();

const char* ai_payload = R"rawliteral({
  "model": "qwen-flash",
  "messages": [...],
  "temperature": 0.7,
  "max_tokens": 150
})rawliteral();

接下来，程序定义了发送给 AI 平台的请求内容。这里使用了 JSON 格式，这是一种广泛应用于互联网的数据交换格式。

请求内容包含四个关键参数：

model：指定要使用的 AI 模型名称，这里是”qwen-flash”
messages：对话内容，包含系统提示和用户问题
temperature：控制 AI 输出的随机性，数值越高回答越有创意
max_tokens：限制 AI 回答的最大长度

代码中使用了 C++ 的原始字符串字面量语法 R"rawliteral(...)rawliteral"，这种写法可以方便地书写多行文本，无需手动处理引号和换行符。

步骤3：创建客户端对象 (第81-85行)

WiFiClientSecure client;  // 安全的HTTPS客户端
HTTPClient https;         // HTTP客户端对象

WiFiClientSecure client;  // 安全的HTTPS客户端
HTTPClient https;         // HTTP客户端对象

为了让 ESP32 能够与 AI 服务器通信，程序创建了两个核心对象：

client（WiFiClientSecure 类型）：负责建立和管理与服务器的安全连接
https（HTTPClient 类型）：负责按照 HTTP 协议发送请求和接收响应

这两个对象各司其职：client 专注于安全连接，https 专注于数据交换。

阶段二：系统启动（setup函数）

ESP32 程序中的 setup() 函数会在开发板启动时执行一次。接下来看看这个函数中都做了些什么。

步骤4：初始化串口 (89-90行)

Serial.begin(115200);
delay(1000);  // 等待串口稳定

Serial.begin(115200);
delay(1000);  // 等待串口稳定

首先启动串口通信，波特率设为 115200。串口是 ESP32 与电脑之间最常用的通信方式，通过它可以在电脑的串口监视器中查看程序运行的信息。

这里等待 1 秒是为了确保串口完全启动，避免后续的打印信息丢失。

步骤5：连接Wi-Fi (第93-103行)

Serial.print("Connecting WiFi");
WiFi.begin(ssid, password);  // 从my_info.h读取WiFi名称和密码
while (WiFi.status() != WL_CONNECTED) {
  delay(500);
  Serial.print(".");
}

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

Serial.print("Connecting WiFi");
WiFi.begin(ssid, password);  // 从my_info.h读取WiFi名称和密码
while (WiFi.status() != WL_CONNECTED) {
  delay(500);
  Serial.print(".");
}

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

然后让 ESP32 连接到 Wi-Fi 网络。程序会不断检查连接状态，直到成功连接为止。连接过程中会在串口监视器打印圆点来显示进度，连接成功后换行显示。

Wi-Fi 连接是后续访问 AI 服务器的前提，只有成功连接网络，才能与互联网上的 AI 平台进行通信。

步骤6：配置HTTPS客户端 (第105-110行)

client.setInsecure();  // 跳过SSL证书验证（仅用于测试！）
client.setTimeout(15);  // 设置15秒超时

client.setInsecure();  // 跳过SSL证书验证（仅用于测试！）
client.setTimeout(15);  // 设置15秒超时

在建立安全连接之前，需要对客户端进行一些配置。

setInsecure() 方法会跳过 SSL 证书验证，这样做的好处是可以简化开发流程。需要注意的是，在正式产品中应该使用有效的 SSL 证书来确保通信安全。

setTimeout(15) 设置了 15 秒的超时时间，如果在规定时间内无法完成操作，程序就会放弃等待。这可以避免程序因为网络问题而无限期卡住。

步骤7：打印配置信息并调用AI平台 (第113-120行)

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

callAIPlatform();  // 发送AI请求

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

callAIPlatform();  // 发送AI请求

准备工作完成后，程序会先在串口监视器上打印 AI 平台的地址信息，然后调用 callAIPlatform() 函数来发送真正的请求。这个函数是程序的核心，负责与 AI 服务器进行通信。

接下来，我们一起重点学习这个 callAIPlatform()函数。

阶段三：发送AI请求（callAIPlatform函数）

callAIPlatform() 函数封装了与 AI 服务器通信的完整流程。接下来一步步分析这个函数的工作过程。

步骤8：构造Authorization请求头（第140-142行）

String auth = "Bearer ";
auth += ai_api_key;  // 从my_info.h读取API密钥

String auth = "Bearer ";
auth += ai_api_key;  // 从my_info.h读取API密钥

首先需要构造身份验证信息。AI 服务器需要确认请求者的身份，这就需要使用 API 密钥。

“Bearer” 是 HTTP 协议中常用的认证方式，后面的 API 密钥就是我们的”通行证”。最终构造出的认证头类似："Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx"。

步骤9：初始化HTTPS连接（第145行）

if (https.begin(client, ai_host, ai_port, ai_endpoint)) {

if (https.begin(client, ai_host, ai_port, ai_endpoint)) {

然后调用 begin() 方法初始化 HTTPS 连接。这个方法需要传入服务器的主机名、端口号和 API 路径等参数。

如果初始化成功，begin() 会返回 true，程序就会继续执行后续操作；否则会跳过这段代码并报错。

步骤10：设置超时时间（第148-149行）

https.setTimeout(20000);      // 20秒超时
https.setConnectTimeout(10000);  // 10秒连接超时

https.setTimeout(20000);      // 20秒超时
https.setConnectTimeout(10000);  // 10秒连接超时

为了提高程序的稳定性，需要设置超时时间。

setTimeout(20000) 设置整个请求的超时时间为 20 秒；setConnectTimeout(10000) 设置建立连接的超时时间为 10 秒。这样即使网络不稳定，程序也不会无限等待。

步骤11：添加HTTP请求头（第154-155行）

https.addHeader("Content-Type", "application/json");
https.addHeader("Authorization", auth);

https.addHeader("Content-Type", "application/json");
https.addHeader("Authorization", auth);

接下来添加 HTTP 请求头。请求头告诉服务器一些必要的信息：

Content-Type: application/json：告诉服务器，我们发送的数据是 JSON 格式
Authorization: auth：告诉服务器我们的身份（API 密钥）

这是 HTTP 协议的标准做法，所有网络请求都需要包含这些信息。

步骤12：发送POST请求（第158行）

int httpCode = https.POST(ai_payload);

int httpCode = https.POST(ai_payload);

一切准备就绪后，调用 POST() 方法将请求发送到 AI 服务器。参数 ai_payload 就是我们在步骤2中定义的 JSON 请求体。

服务器返回的 HTTP 状态码会被保存到 httpCode 变量中。常见的状态码有：200 表示成功，404 表示找不到资源，500 表示服务器错误等。

步骤13：处理响应（第160-177行）

    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);
    }

    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);
    }

收到服务器响应后，需要判断请求是否成功。

首先检查 httpCode 是否大于 0：如果大于 0，说明请求已经成功发送并收到了响应；如果小于等于 0，说明请求失败（比如无法连接服务器）。

如果状态码是 200（HTTP_CODE_OK），说明请求成功。这时调用 getString() 方法读取服务器的响应内容，并在串口监视器中打印出来。

如果请求失败，会打印错误信息，帮助开发者了解问题所在。

步骤14：结束HTTP会话（第190行）

https.end();

https.end();

最后调用 end() 方法关闭与服务器的连接，释放占用的资源。这是良好的编程习惯，可以避免内存泄漏等问题。

阶段四：主循环

步骤15：空循环（第131-133行）

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

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

ESP32 程序中的 loop() 函数会在 setup() 执行完后反复运行。但在本例中，这个函数是空的，因为我们只需要发送一次 AI 请求，不需要重复执行。

总结

这个程序展示了 ESP32 调用 AI 平台的基本流程：先连接 Wi-Fi，然后构造请求、发送请求、处理响应，最后释放资源。理解了这个基础流程后，就可以进一步学习如何实现多轮对话、功能更复杂的 AI 应用了。