尧图网站建设 
CAI SDK 配置实战指南API 密钥、Tracing 与调试日志的完整配置方案【免费下载链接】caiCybersecurity AI (CAI), the framework for AI Security项目地址: https://gitcode.com/GitHub_Trending/cai3/cai本文以 CAICybersecurity AI开源仓库中的 SDK 配置文档 为骨架系统讲解 CAI SDK 的三大配置域LLM 请求的 API 密钥与客户端、默认开启的 Tracing 追踪链路以及面向排障的调试日志体系。通过本文你将掌握set_default_openai_key/set_default_openai_client/set_default_openai_api等一组全局配置函数的使用时机与参数语义理解 Tracing 导出管道的底层实现BackendSpanExporterBatchTraceProcessor并能按需关闭敏感数据日志、控制日志级别为在安全测试、红队自动化等场景下稳定运行 CAI Agent 打好配置基础。一、API 密钥与客户端SDK 配置的第一道入口CAI SDK 在导入import时即开始为 LLM 请求与 Tracing 解析凭据。其默认行为是查找OPENAI_API_KEY环境变量因此最常见的初始化方式就是在启动应用前完成环境变量的注入。1.1 环境变量优先代码设置兜底如果应用启动前无法设置OPENAI_API_KEYSDK 提供了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_tracingTrue会同步调用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.AsyncClientshared_http_client()见同文件 L19-L23以复用连接池、降低延迟与资源占用。1.3 切换 OpenAI API 形态Responses 与 Chat CompletionsCAI 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返回OpenAIResponsesModelFalse返回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在纯离线或隐私敏感场景可以整体禁用 Tracingfrom 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_TRACINGtrue或1。该变量在 TraceProvider 初始化 时被读取是「进程级默认开关」。2.3 导出管道原理批量处理器与指数退避理解 Tracing 的底层有助于评估其性能影响。默认处理器是BatchTraceProcessorprocessors.py其设计要点包括使用线程安全的queue.Queue缓存 trace/span队列上限max_queue_size8192超出即丢弃并告警由后台守护线程定时schedule_delay5.0s或按队列水位达到 70% 容量即触发批量导出单批上限max_batch_size128网络失败时采用指数退避 抖动重试最多max_retries3次基础延迟 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 loggeropenai.agentsSDK 主体日志openai.agents.tracingTracing 子模块日志。对应实现见 logger.pytracing 子模块在tracing/setup.py、tracing/processors.py中复用该 logger。由于默认没有任何 handlerwarning 及以上级别会走 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操作 loggerimport 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_DATA1 # 禁止记录工具输入与输出 export OPENAI_AGENTS_DONT_LOG_TOOL_DATA1这两个开关应在进程启动前设置适用于处理真实环境数据的安全测试、红队评估等场景。若需要更系统的日志与遥测策略可结合 环境变量参考文档 中的CAI_DEBUG、CAI_TRACING等变量统一规划其中CAI_DEBUG控制 REPL/CLI 层级的调试输出级别02CAI_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_urlhttps://my-gateway.example/v1, api_keysk-gw-...) set_default_openai_client(custom_client, use_for_tracingFalse) # 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_KEYsk-... export OPENAI_AGENTS_DONT_LOG_MODEL_DATA1 export OPENAI_AGENTS_DONT_LOG_TOOL_DATA1五、相关资源与延伸阅读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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CAI SDK 配置实战指南：API 密钥、Tracing 与调试日志的完整配置方案
CAI SDK 配置实战指南API 密钥、Tracing 与调试日志的完整配置方案【免费下载链接】caiCybersecurity AI (CAI), the framework for AI Security项目地址: https://gitcode.com/GitHub_Trending/cai3/cai本文以 CAICybersecurity AI开源仓库中的 SDK 配置文档 为骨架系统讲解 CAI SDK 的三大配置域LLM 请求的 API 密钥与客户端、默认开启的 Tracing 追踪链路以及面向排障的调试日志体系。通过本文你将掌握set_default_openai_key/set_default_openai_client/set_default_openai_api等一组全局配置函数的使用时机与参数语义理解 Tracing 导出管道的底层实现BackendSpanExporterBatchTraceProcessor并能按需关闭敏感数据日志、控制日志级别为在安全测试、红队自动化等场景下稳定运行 CAI Agent 打好配置基础。一、API 密钥与客户端SDK 配置的第一道入口CAI SDK 在导入import时即开始为 LLM 请求与 Tracing 解析凭据。其默认行为是查找OPENAI_API_KEY环境变量因此最常见的初始化方式就是在启动应用前完成环境变量的注入。1.1 环境变量优先代码设置兜底如果应用启动前无法设置OPENAI_API_KEYSDK 提供了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_tracingTrue会同步调用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.AsyncClientshared_http_client()见同文件 L19-L23以复用连接池、降低延迟与资源占用。1.3 切换 OpenAI API 形态Responses 与 Chat CompletionsCAI 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返回OpenAIResponsesModelFalse返回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在纯离线或隐私敏感场景可以整体禁用 Tracingfrom 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_TRACINGtrue或1。该变量在 TraceProvider 初始化 时被读取是「进程级默认开关」。2.3 导出管道原理批量处理器与指数退避理解 Tracing 的底层有助于评估其性能影响。默认处理器是BatchTraceProcessorprocessors.py其设计要点包括使用线程安全的queue.Queue缓存 trace/span队列上限max_queue_size8192超出即丢弃并告警由后台守护线程定时schedule_delay5.0s或按队列水位达到 70% 容量即触发批量导出单批上限max_batch_size128网络失败时采用指数退避 抖动重试最多max_retries3次基础延迟 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 loggeropenai.agentsSDK 主体日志openai.agents.tracingTracing 子模块日志。对应实现见 logger.pytracing 子模块在tracing/setup.py、tracing/processors.py中复用该 logger。由于默认没有任何 handlerwarning 及以上级别会走 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操作 loggerimport 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_DATA1 # 禁止记录工具输入与输出 export OPENAI_AGENTS_DONT_LOG_TOOL_DATA1这两个开关应在进程启动前设置适用于处理真实环境数据的安全测试、红队评估等场景。若需要更系统的日志与遥测策略可结合 环境变量参考文档 中的CAI_DEBUG、CAI_TRACING等变量统一规划其中CAI_DEBUG控制 REPL/CLI 层级的调试输出级别02CAI_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_urlhttps://my-gateway.example/v1, api_keysk-gw-...) set_default_openai_client(custom_client, use_for_tracingFalse) # 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_KEYsk-... export OPENAI_AGENTS_DONT_LOG_MODEL_DATA1 export OPENAI_AGENTS_DONT_LOG_TOOL_DATA1五、相关资源与延伸阅读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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考