AI API客户端使用说明文档

1. 项目概述

这是一个基于WinHTTP的C++轻量级AI大模型API调用库，专为Windows平台设计。通过封装原生HTTP协议和JSON处理，提供了简洁易用的接口来调用各类AI大模型API（如OpenAI、Claude、通义千问等）。

核心特点

• 纯C++实现，仅依赖Windows SDK和nlohmann/json库
• 同步调用模式，适合大多数应用场景
• 智能重试机制，自动处理网络波动和限流
• UTF-8/UTF-16自动转换，完美支持中英文
• 类型安全，使用std::variant和强枚举避免错误

---

2. 核心原理解析

2.1 架构设计

┌─────────────────────────────────────────┐
│         ai_api_client (主类)            │
├─────────────────────────────────────────┤
│  - 会话管理 (WinHTTP会话句柄)           │
│  - 配置存储 (request_config)            │
│  - HTTP执行引擎 (perform_http_request)  │
│  - JSON处理器 (build/parse)             │
└─────────────────────────────────────────┘
          ↓ 依赖
┌─────────────────────────────────────────┐
│  工具命名空间                          │
│  - encoding_utils: 字符编码转换        │
│  - url_utils: URL解析                  │
│  - json_utils: JSON序列化              │
└─────────────────────────────────────────┘

2.2 工作流程

1. 配置阶段：创建request_config对象，设置API密钥、模型、参数等
2. 请求构建：将C++结构体（chat_message）序列化为JSON格式
3. HTTP通信：
   • 初始化WinHTTP会话（连接复用）
   • 自动处理HTTPS/TLS握手
   • 设置超时和重试策略
4. 响应处理：解析JSON响应，提取内容、token统计等信息
5. 错误处理：分类错误码，提供详细诊断信息

---

3. 快速开始

3.1 环境要求

• 操作系统：Windows 7 或更高版本
• 编译器：支持C++17的MSVC（Visual Studio 2019+）
• 依赖库：
  • nlohmann/json（仅需头文件）
  • Windows SDK（已内置WinHTTP）

3.2 安装步骤

1. 下载JSON库：

# 通过vcpkg安装
vcpkg install nlohmann-json

# 或直接下载单头文件
# https://github.com/nlohmann/json/releases/download/v3.11.3/json.hpp

2. 配置项目：

   • 将本头文件加入项目
   • 添加包含路径：#include <nlohmann/json.hpp>
   • 链接库：在项目属性中添加 winhttp.lib

3. 示例代码：

#include "_call_for_AI_flow.h"
#include <iostream>

int main() {
    try {
        // 1. 创建配置
        ai_client::request_config config;
        config.api_url = "https://api.openai.com/v1";
        config.api_key = "sk-xxxxxxxxxxxxxxxxxxxx";
        config.model = "gpt-3.5-turbo";
        config.temperature = 0.7;
        config.max_tokens = 2048;
        config.timeout_seconds = 30;

        // 2. 创建客户端
        ai_client::ai_api_client client(config);

        // 3. 添加对话历史
        client.add_message(ai_client::message_role::system, "你是一个乐于助人的助手");
        client.add_message(ai_client::message_role::user, "你好，请介绍一下C++17的特性");

        // 4. 发送请求
        auto response = client.send_chat_request();

        // 5. 处理响应
        if (response.is_success()) {
            std::cout << "AI回复: " << response.content << std::endl;
            std::cout << "使用token: " << response.total_tokens << std::endl;
        } else {
            std::cerr << "错误: " << response.error_message << std::endl;
        }

    } catch (const std::exception& e) {
        std::cerr << "异常: " << e.what() << std::endl;
    }
    return 0;
}

---

4. API详解

4.1 核心配置结构（request_config）

参数	类型	默认值	说明
api_url	string	-	API基础URL（如https://api.openai.com/v1）
api_key	string	-	认证密钥，必需
model	string	-	模型名称（如gpt-4）
temperature	double	0.7	控制随机性（0-2）
top_p	double	1.0	核采样概率（0-1）
top_k	int	-1	Top-K采样（-1禁用）
max_tokens	int	2048	最大生成长度
stream	bool	false	是否流式输出（当前仅同步）
timeout_seconds	int	30	超时时间（秒）
max_retries	int	3	网络错误重试次数
retry_delay_ms	int	1000	重试延迟（毫秒），指数退避

配置示例：

config.temperature = 0.8;      // 更具创造性
config.max_tokens = 4096;      // 支持长文本
config.presence_penalty = 1.0; // 避免重复话题
config.frequency_penalty = 0.5; // 降低高频词权重

4.2 消息管理接口

// 添加文本消息（UTF-8）
void add_message(message_role role, const string& content, const string& name = "");

// 添加文本消息（UTF-16），自动转换
void add_message(message_role role, const wstring& content_w, const string& name = "");

// 清空对话历史
void clear_context();

角色枚举：

• message_role::system：系统指令，设定AI行为
• message_role::user：用户输入
• message_role::assistant：AI回复（用于多轮对话）
• message_role::function/tool：函数调用结果

消息链示例：

// 多轮对话
client.add_message(ai_client::message_role::system, "你是一名资深程序员");
client.add_message(ai_client::message_role::user, "C++如何管理内存？");
client.add_message(ai_client::message_role::assistant, 
    "C++主要使用RAII、智能指针...");
client.add_message(ai_client::message_role::user, "能详细解释RAII吗？");
auto response = client.send_chat_request();

4.3 响应数据结构（response_data）

字段	类型	说明
error	error_code	错误码枚举
error_message	string	人类可读错误描述
content	string	AI生成的文本内容
model_used	string	实际使用的模型
total_tokens	int	总token消耗
prompt_tokens	int	输入token数
completion_tokens	int	生成token数
finish_reason	string	停止原因（stop, length等）
raw_response	string	完整JSON响应（调试用）
http_status_code	int	HTTP状态码
elapsed_time	chrono::milliseconds	请求耗时

响应检查：

if (response.is_success()) { // 检查error==success && http_status==200
    // 使用response.content
} else {
    // 查看response.error_message
    // 查看response.error获取错误类型
}

---

5. 高级用法

5.1 动态参数调整

ai_client::ai_api_client client;

// 运行时修改配置
client.set_api_key("new-key");
client.set_model("gpt-4-turbo-preview");
client.set_temperature(0.3); // 降低随机性
client.set_max_tokens(8000); // 扩展输出

// 添加自定义HTTP头（如组织ID）
config.custom_headers["OpenAI-Organization"] = "org-xxxxxx";

5.2 错误处理与重试

库内置智能重试逻辑，自动处理：

• 网络错误：连接失败、超时
• 限流错误：HTTP 429（Rate Limit）
• 服务器错误：HTTP 5xx

自定义重试策略：

config.max_retries = 5;           // 最多重试5次
config.retry_delay_ms = 2000;     // 初始延迟2秒（实际延迟=retry_count * delay）

手动错误处理：

auto response = client.send_chat_request();

switch (response.error) {
    case ai_client::error_code::success:
        // 成功处理
        break;
    case ai_client::error_code::rate_limit_exceeded:
        std::cerr << "触发限流，请稍后重试" << std::endl;
        break;
    case ai_client::error_code::authentication_failed:
        std::cerr << "API密钥无效" << std::endl;
        break;
    case ai_client::error_code::timeout:
        std::cerr << "请求超时，网络可能不稳定" << std::endl;
        break;
    default:
        std::cerr << "未知错误: " << response.error_message << std::endl;
}

5.3 连接复用与性能优化

原理：ai_api_client在首次请求时创建WinHTTP会话，后续请求复用连接（HTTP keep-alive），显著提升性能。

最佳实践：

// 重用客户端实例（推荐）
ai_client::ai_api_client client(config);

// 多次调用（自动复用连接）
for (int i = 0; i < 100; ++i) {
    client.clear_context();
    client.add_message(ai_client::message_role::user, prompt[i]);
    auto resp = client.send_chat_request();
    // 处理响应...
}

// 需要切换API时重建连接
client.set_api_url("https://api.anthropic.com/v1"); // 触发会话重建

性能统计：

auto resp = client.send_chat_request();
std::cout << "耗时: " << resp.elapsed_time.count() << "ms\n";
std::cout << "输入: " << resp.prompt_tokens << " tokens\n";
std::cout << "输出: " << resp.completion_tokens << " tokens\n";

---

6. 多平台适配说明

6.1 API端点配置

OpenAI：

config.api_url = "https://api.openai.com/v1";
config.model = "gpt-4-turbo-preview";

Azure OpenAI：

config.api_url = "https://your-resource.openai.azure.com/openai/deployments/your-deployment";
config.custom_headers["api-key"] = "your-azure-key";

通义千问（DashScope）：

config.api_url = "https://dashscope.aliyuncs.com/api/v1";
config.api_key = "sk-xxxxxxxx";
config.model = "qwen-max";

Claude（Anthropic）：

config.api_url = "https://api.anthropic.com/v1";
config.api_key = "sk-ant-xxxxxx";
config.model = "claude-3-opus-20240229";
config.custom_headers["anthropic-version"] = "2023-06-01";

---

7. 调试与日志

7.1 获取原始响应

auto resp = client.send_chat_request();
if (!resp.is_success()) {
    std::cerr << "HTTP状态码: " << resp.http_status_code << std::endl;
    std::cerr << "原始响应: " << resp.raw_response << std::endl;
}

7.2 常见错误码

错误码	HTTP状态	典型原因
authentication_failed	401	API密钥错误或已过期
model_not_found	404	模型名称拼写错误
rate_limit_exceeded	429	超出QPS或TPM限制
server_error	500/502/503	服务端故障
invalid_json	200	响应格式异常，可能API版本不兼容

---

8. 注意事项与最佳实践

⚠️ 重要提醒

1. 线程安全：ai_api_client实例非线程安全，多线程请使用独立实例

   // 错误：多线程共享同一个client
   // 正确：每个线程创建独立client

2. 内存管理：消息历史会累积，长对话需定期清理

   if (config.messages.size() > 50) {
       client.clear_context();
       // 保留最近的系统提示
       client.add_message(ai_client::message_role::system, system_prompt);
   }

3. Token限制：max_tokens + 输入token之和不能超过模型上限

   // 建议预留token空间
   config.max_tokens = model_max_tokens - estimated_prompt_tokens - 500;

4. 超时设置：推理型模型（如o1）需增大超时

   config.timeout_seconds = 180; // 3分钟，适应长思考

5. 代理支持：WinHTTP自动使用系统代理，企业环境需确保代理配置正确

💡 性能建议

• 批量请求：使用连接复用，避免频繁创建客户端
• 精简消息：定期清理无关历史，减少token消耗和传输时间
• 合理超时：根据模型响应速度调整，避免过早超时
• 错误重试：对限流错误使用指数退避策略（库已内置）

---

9. 完整示例：智能对话系统

#include "_call_for_AI_flow.h"
#include <iostream>
#include <string>

class SmartAssistant {
private:
    ai_client::ai_api_client client;
    
public:
    SmartAssistant(const string& api_key) {
        ai_client::request_config config;
        config.api_url = "https://api.openai.com/v1";
        config.api_key = api_key;
        config.model = "gpt-4";
        config.temperature = 0.7;
        config.max_tokens = 2048;
        config.timeout_seconds = 60;
        
        client.set_config(config);
        client.add_message(ai_client::message_role::system, 
            "你是AI助手Eva，专业、简洁、技术导向");
    }
    
    string chat(const string& user_input) {
        client.add_message(ai_client::message_role::user, user_input);
        
        auto resp = client.send_chat_request();
        
        if (resp.is_success()) {
            // 保存AI回复到上下文
            client.add_message(ai_client::message_role::assistant, resp.content);
            return resp.content;
        } else {
            // 移除失败的用户消息
            client.config.messages.pop_back();
            return "错误: " + resp.error_message;
        }
    }
    
    void clear_memory() {
        auto system_msg = client.config.messages.front(); // 保留系统提示
        client.clear_context();
        client.config.messages.push_back(system_msg);
    }
};

int main() {
    try {
        SmartAssistant assistant("sk-your-api-key");
        
        while (true) {
            std::cout << "\n用户: ";
            std::string input;
            std::getline(std::cin, input);
            
            if (input == "/bye") break;
            if (input == "/clear") {
                assistant.clear_memory();
                std::cout << "上下文已清空\n";
                continue;
            }
            
            std::cout << "AI: " << assistant.chat(input) << std::endl;
        }
    } catch (const std::exception& e) {
        std::cerr << "致命错误: " << e.what() << std::endl;
    }
    
    return 0;
}

---

10. 版本历史

版本	日期	更新内容
1.0	2024-12-08	初始实现，支持OpenAI兼容API
1.1	2025-01-15	增加代理支持、UTF-16接口
1.2	2025-03-20	优化重试逻辑，支持Azure OpenAI

---

11. 许可证

本项目采用 MIT License，可自由用于商业和个人项目。

---

文档版本：1.2 | 最后更新：2025-12-08 | 维护：AI Flow Team