CAI SDK 配置实战指南：API 密钥、Tracing 与调试日志的完整配置方案

CAI SDK 配置实战指南：API 密钥、Tracing 与调试日志的完整配置方案

【免费下载链接】caiCybersecurity AI (CAI), the framework for AI Security项目地址: https://gitcode.com/GitHub_Trending/cai3/cai

本文以 CAI（Cybersecurity AI）开源仓库中的 SDK 配置文档 为骨架，系统讲解 CAI SDK 的三大配置域：LLM 请求的 API 密钥与客户端、默认开启的 Tracing 追踪链路，以及面向排障的调试日志体系。通过本文，你将掌握set_default_openai_key/set_default_openai_client/set_default_openai_api等一组全局配置函数的使用时机与参数语义，理解 Tracing 导出管道的底层实现（BackendSpanExporter+BatchTraceProcessor），并能按需关闭敏感数据日志、控制日志级别，为在安全测试、红队自动化等场景下稳定运行 CAI Agent 打好配置基础。

一、API 密钥与客户端：SDK 配置的第一道入口

CAI SDK 在导入（import）时即开始为 LLM 请求与 Tracing 解析凭据。其默认行为是查找OPENAI_API_KEY环境变量，因此最常见的初始化方式就是在启动应用前完成环境变量的注入。

1.1 环境变量优先，代码设置兜底

如果应用启动前无法设置OPENAI_API_KEY，SDK 提供了set_default_openai_key()函数在运行时注入密钥：

from cai.sdk.agents import set_default_openai_key set_default_openai_key("sk-...")

从源码看，该函数定义于 SDK 入口模块，其签名与语义为：

• key：要使用的 OpenAI API 密钥；
• use_for_tracing：是否同时将该密钥用于向 OpenAI 上报 trace，默认True。若设为False，则 Tracing 导出仍需依赖OPENAI_API_KEY环境变量，或显式调用set_tracing_export_api_key()。

实际生效逻辑位于 配置层实现：设置密钥后，若use_for_tracing=True，会同步调用set_tracing_export_api_key(key)，从而保证 LLM 请求与 Tracing 使用同一凭据。全局状态保存在 全局默认配置 的模块级变量_default_openai_key中。

1.2 自定义 OpenAI 客户端：突破默认 endpoint

默认情况下，SDK 会以环境变量或默认密钥创建AsyncOpenAI实例。若需要接入代理网关、兼容端点或本地推理服务（如 Ollama、vLLM 等提供 OpenAI 兼容 API 的服务），可通过set_default_openai_client()替换整个客户端：

from openai import AsyncOpenAI from cai.sdk.agents import set_default_openai_client custom_client = AsyncOpenAI(base_url="...", api_key="...") set_default_openai_client(custom_client)

该函数同样支持use_for_tracing参数（默认True）。当为真时，SDK 会取出client.api_key作为 Tracing 导出密钥（见 _config.py）。其底层实现把客户端实例存入_default_openai_client全局变量（models/_openai_shared.py），后续所有模型请求在创建客户端时都会优先复用该实例。

值得强调的是，OpenAIProvider 的实现 采用懒加载策略：只有真正发起请求时才创建AsyncOpenAI客户端，且解析顺序为「默认客户端 → 构造时传入的 api_key → 全局默认密钥」，最后还会注入共享的httpx.AsyncClient（shared_http_client()，见同文件 L19-L23）以复用连接池、降低延迟与资源占用。

1.3 切换 OpenAI API 形态：Responses 与 Chat Completions

CAI SDK 默认使用 OpenAIResponses API。若要切换到传统的Chat Completions API，调用：

from cai.sdk.agents import set_default_openai_api set_default_openai_api("chat_completions")

参数类型为字面量Literal["chat_completions", "responses"]。其底层通过_openai_shared.set_use_responses_by_default(...)翻转全局开关_use_responses_by_default（默认True，见 models/_openai_shared.py 与 _config.py）。

当OpenAIProvider.get_model()被调用时，会依据该开关选择具体实现：True返回OpenAIResponsesModel，False返回OpenAIChatCompletionsModel（见 openai_provider.py）。此外，每个OpenAIProvider构造时也可通过use_responses参数进行单例级覆盖，优先级高于全局默认值。

小结：密钥、客户端、API 形态三层配置均遵循「环境变量 → 全局默认 → 单例覆盖」的优先级链条，理解这条链路有助于在复杂接入场景中快速定位凭据来源。

二、Tracing：默认开启的调用链追踪与导出配置

CAI SDK 的 Tracing默认开启，它使用与 LLM 请求相同的密钥（即OPENAI_API_KEY环境变量或上述设置的默认密钥）。每次 Agent 运行都会生成 trace，并由后台线程批量导出。

2.1 为 Tracing 单独指定导出密钥

当希望 LLM 请求与 Trace 上报使用不同账号/密钥时，调用set_tracing_export_api_key()：

from cai.sdk.agents import set_tracing_export_api_key set_tracing_export_api_key("sk-...")

从 Tracing 顶层 API 可见，该函数直接作用于默认导出器：default_exporter().set_api_key(api_key)。导出器为 BackendSpanExporter，其默认上报端点为https://api.openai.com/v1/traces/ingest，密钥解析顺序为「显式设置的 api_key →OPENAI_API_KEY环境变量」（cached_property api_key，见 processors.py L76-L78），并支持OPENAI_ORG_ID、OPENAI_PROJECT_ID分别覆盖组织与项目维度。

2.2 全局关闭 Tracing

在纯离线或隐私敏感场景，可以整体禁用 Tracing：

from cai.sdk.agents import set_tracing_disabled set_tracing_disabled(True)

该调用会把GLOBAL_TRACE_PROVIDER的_disabled置为True（见 tracing/init.py 与 setup.py）。此后create_trace/create_span会直接返回NoOpTrace/NoOpSpan，避免产生任何导出开销（见 setup.py L132-L134、L158-L160）。

除代码方式外，还可以通过环境变量在进程启动时禁用：OPENAI_AGENTS_DISABLE_TRACING=true（或1）。该变量在 TraceProvider 初始化 时被读取，是「进程级默认开关」。

2.3 导出管道原理：批量处理器与指数退避

理解 Tracing 的底层有助于评估其性能影响。默认处理器是BatchTraceProcessor（processors.py），其设计要点包括：

• 使用线程安全的queue.Queue缓存 trace/span，队列上限max_queue_size=8192，超出即丢弃并告警；
• 由后台守护线程定时（schedule_delay=5.0s）或按队列水位（达到 70% 容量即触发）批量导出，单批上限max_batch_size=128；
• 网络失败时采用指数退避 + 抖动重试，最多max_retries=3次，基础延迟 1 秒、最大 30 秒；4xx 客户端错误不重试，5xx 与网络错误才重试；
• 进程退出时通过atexit注册的GLOBAL_TRACE_PROVIDER.shutdown()排空剩余队列（见 tracing/init.py）。

如果需要自定义导出目的地（例如自建 trace 平台），可以通过add_trace_processor()追加处理器，或用set_trace_processors()整体替换默认处理器。详细接口可参考 docs/tracing.md 与 docs/tracing_cai.md。

三、调试日志：从静默到逐条可见

CAI SDK 内置两个无任何 handler 的 Python logger：

• openai.agents：SDK 主体日志；
• openai.agents.tracing：Tracing 子模块日志。

（对应实现见 logger.py，tracing 子模块在tracing/setup.py、tracing/processors.py中复用该 logger。）

由于默认没有任何 handler，warning 及以上级别会走 Python 的 lastResort handler 输出到stdout，其余级别默认被抑制。

3.1 一键开启冗长日志

调试排障时可直接启用：

from cai.sdk.agents import enable_verbose_stdout_logging enable_verbose_stdout_logging()

其实现（见init.py）等价于：将openai.agentslogger 级别设为DEBUG，并挂载一个输出到sys.stdout的StreamHandler。开启后，Agent 创建、trace/span 生命周期、导出失败重试等内部事件都会逐条可见。

3.2 精细定制：标准 logging API

若需要更细的控制（如按模块过滤、写入文件、定制格式），直接使用标准库logging操作 logger：

import logging logger = logging.getLogger("openai.agents") # 或 openai.agents.tracing # 按需选择日志级别 logger.setLevel(logging.DEBUG) # 全部日志 logger.setLevel(logging.INFO) # info 及以上 logger.setLevel(logging.WARNING) # warning 及以上 # ... # 添加处理器（默认输出到 stderr） logger.addHandler(logging.StreamHandler())

这与标准 Python logging 指南中的 handler/filter/formatter 用法完全一致，可以自由组合FileHandler、RotatingFileHandler或自定义 Formatter，实现日志落盘、轮转与结构化输出。

3.3 敏感数据脱敏：两个环境变量开关

某些日志（例如用户数据、Prompt 内容、工具调用参数与结果）可能包含敏感信息。CAI SDK 提供两个环境变量用于禁止此类数据进入日志：

# 禁止记录 LLM 输入与输出 export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1 # 禁止记录工具输入与输出 export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1

这两个开关应在进程启动前设置，适用于处理真实环境数据的安全测试、红队评估等场景。若需要更系统的日志与遥测策略，可结合 环境变量参考文档 中的CAI_DEBUG、CAI_TRACING等变量统一规划：其中CAI_DEBUG控制 REPL/CLI 层级的调试输出级别（0～2），CAI_TRACING控制 OpenTelemetry 追踪的开关，二者与 SDK 层的日志配置互为补充。

四、配置总览与典型组合

将三部分配置组合起来，一个「自定义网关 + Chat Completions + 单独 trace 密钥 + 关闭模型数据日志」的完整初始化示例如下：

from openai import AsyncOpenAI from cai.sdk.agents import ( set_default_openai_client, set_default_openai_api, set_tracing_export_api_key, enable_verbose_stdout_logging, ) # 1) 自定义客户端（网关 / 兼容端点） custom_client = AsyncOpenAI(base_url="https://my-gateway.example/v1", api_key="sk-gw-...") set_default_openai_client(custom_client, use_for_tracing=False) # 2) 切换到 Chat Completions API set_default_openai_api("chat_completions") # 3) 为 Tracing 单独指定导出密钥 set_tracing_export_api_key("sk-trace-...") # 4) 开启详细日志便于排障 enable_verbose_stdout_logging()

对应地，在 shell 中预置环境变量可以替代部分代码：

export OPENAI_API_KEY="sk-..." export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1 export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1

五、相关资源与延伸阅读

• SDK 配置文档（本文来源）
• 环境变量参考：CAI 全量环境变量、默认值与 REPL 内/config、/help var查看方式
• Tracing 文档 与 CAI Tracing 文档：trace/span 模型与处理器自定义
• API 参考：更多 SDK 编程接口
• 源码入口：配置层实现、全局默认配置、OpenAI 模型提供方、Tracing 导出管道、TraceProvider 全局实例

结语

CAI SDK 的配置体系围绕「密钥 → 客户端 → API 形态 → Tracing → 日志」五条主线展开：前三者决定 LLM 请求如何发出，Tracing 决定调用链如何采集与导出，日志则决定排障时能看到多少细节。结合本文给出的源码路径（_config.py、_openai_shared.py、processors.py等），开发者既能完成开箱即用的最小配置，也能在网关接入、隐私合规、性能调优等进阶场景中精准定位并覆盖默认行为。

【免费下载链接】caiCybersecurity AI (CAI), the framework for AI Security项目地址: https://gitcode.com/GitHub_Trending/cai3/cai