CONFIG_EXAMPLES.md

Cognitive Kernel-Pro 配置示例

本文档提供完整的TOML配置文件示例，帮助您根据不同的使用场景进行配置。

📋 配置选项总览

快速开始选项

方法	适用场景	配置复杂度	推荐指数
环境变量	新用户快速开始	⭐	⭐⭐⭐⭐⭐
最小配置	标准使用	⭐⭐	⭐⭐⭐⭐
全面配置	高级定制	⭐⭐⭐⭐⭐	⭐⭐⭐

🚀 环境变量方式 (推荐新用户)

无需配置文件，直接使用环境变量：

# 设置环境变量
export OPENAI_API_BASE="https://api.openai.com/v1/chat/completions"
export OPENAI_API_KEY="your-api-key-here"
export OPENAI_API_MODEL="gpt-4o-mini"

# 运行
python -m ck_pro --input "What is AI?"

优势

• ✅ 零配置：无需创建任何文件
• ✅ 快速启动：5秒内开始使用
• ✅ 容器友好：完美支持Docker/K8s
• ✅ 安全管理：敏感信息环境变量管理

📁 最小配置文件

适用于大多数标准使用场景，只需要配置核心组件。

# config.minimal.toml
[ck.model]
call_target = "https://api.openai.com/v1/chat/completions"
api_key = "your-api-key-here"
model = "gpt-4o-mini"

[ck.model.extract_body]
temperature = 0.6
max_tokens = 4000

[ck]
max_steps = 16
max_time_limit = 600

[search]
backend = "duckduckgo"

使用方法

cp config.minimal.toml config.toml
# 编辑config.toml中的API密钥
python -m ck_pro --input "What is AI?"

⚙️ 全面配置文件

包含所有可用配置选项，适用于需要完全控制系统的场景。

# config.comprehensive.toml - 完整示例见同目录文件
[ck]
name = "ck_agent"
description = "Cognitive Kernel, an initial autopilot system."
max_steps = 16
max_time_limit = 6000
recent_steps = 5
obs_max_token = 8192
exec_timeout_with_call = 1000
exec_timeout_wo_call = 200
end_template = "more"

[ck.model]
call_target = "https://api.openai.com/v1/chat/completions"
api_key = "your-openai-api-key"
model = "gpt-4o-mini"
request_timeout = 600
max_retry_times = 5
max_token_num = 20000

# ... 更多配置选项见 config.comprehensive.toml

🔧 配置说明

核心配置 [ck]

参数	默认值	说明
name	"ck_agent"	代理名称
max_steps	16	最大推理步骤数
max_time_limit	6000	最大执行时间(秒)
end_template	"more"	结束模板详细程度

模型配置 [ck.model]

参数	类型	说明
call_target	string	API端点URL
api_key	string	API密钥
model	string	模型名称
request_timeout	int	请求超时时间
max_retry_times	int	最大重试次数

Web代理配置 [web]

参数	默认值	说明
max_steps	20	Web任务最大步骤数
use_multimodal	"auto"	是否使用多模态(off/yes/auto)

文件代理配置 [file]

参数	默认值	说明
max_steps	16	文件处理最大步骤数
max_file_read_tokens	3000	文件读取最大token数
max_file_screenshots	2	文件截图最大数量

日志配置 [logging]

参数	默认值	说明
console_level	"INFO"	控制台日志级别
log_dir	"logs"	日志目录
session_logs	true	是否启用会话日志

搜索配置 [search]

参数	默认值	说明
backend	"duckduckgo"	搜索引擎(duckduckgo/google)

🎯 优先级顺序

配置值的优先级从高到低：

1. TOML配置文件 - 最高优先级
2. 继承机制 - 子组件继承父组件设置
3. 环境变量 - 中等优先级
4. 硬编码默认值 - 最低优先级

继承示例

[ck.model]
call_target = "https://api.openai.com/v1/chat/completions"
api_key = "shared-key"

[web.model]
# 自动继承 call_target 和 api_key
model = "gpt-4-vision"  # 只覆盖模型名称

[file.model]
call_target = "https://different-api.com"  # 覆盖继承的设置
api_key = "different-key"  # 覆盖继承的设置
model = "claude-3-sonnet"  # 指定不同模型

🚀 快速开始指南

场景1: 新用户快速开始

# 方式1: 环境变量 (推荐)
export OPENAI_API_KEY="your-key"
export OPENAI_API_MODEL="gpt-4o-mini"
python -m ck_pro --input "Hello world"

# 方式2: 最小配置
cp config.minimal.toml config.toml
# 编辑API密钥
python -m ck_pro --config config.toml --input "Hello world"

场景2: 多模型配置

[ck.model]
call_target = "https://api.openai.com/v1/chat/completions"
api_key = "openai-key"
model = "gpt-4o-mini"

[web.model]
call_target = "https://api.siliconflow.cn/v1/chat/completions"
api_key = "siliconflow-key"
model = "Kimi-K2-Instruct"

[file.model]
call_target = "https://api-inference.modelscope.cn/v1/chat/completions"
api_key = "modelscope-key"
model = "Qwen/Qwen3-235B-A22B-Instruct-2507"

场景3: 生产环境部署

# Docker环境变量注入
docker run -e OPENAI_API_KEY="prod-key" \
           -e OPENAI_API_MODEL="gpt-4o" \
           cognitivekernel-pro

# Kubernetes ConfigMap
apiVersion: v1
kind: ConfigMap
metadata:
  name: ck-config
data:
  OPENAI_API_BASE: "https://api.openai.com/v1/chat/completions"
  OPENAI_API_MODEL: "gpt-4o"

❓ 常见问题

Q: 配置文件不存在会怎样？

A: 系统会自动使用环境变量或硬编码默认值，不会出现错误。

Q: 如何验证配置是否正确？

A: 运行简单查询测试：python -m ck_pro --input "test"

Q: 支持哪些模型？

A: 支持所有兼容OpenAI API格式的模型，包括GPT、Claude、Qwen等。

Q: 如何切换不同的模型配置？

A: 修改config.toml中的[ck.model]、[web.model]、[file.model]部分。

📚 相关文档

• readme.md - 项目主要文档
• docs/ARCH.md - 架构设计文档
• docs/PLAYWRIGHT_BUILTIN.md - Web自动化文档