支持消融实验的上下文感知 AI Agent

源文件：chapter1/context/README.md

支持消融实验的上下文感知 AI Agent

一个进阶 AI Agent 实现，支持多种 LLM 提供方（SiliconFlow Qwen、字节跳动豆包、Moonshot Kimi、DeepSeek），通过系统化的消融实验直观展示上下文各组件的关键作用。

🎯 概览

本项目实现了一个上下文感知的 AI Agent，内置多种工具（PDF 解析、汇率换算、计算器、代码解释器），并提供完整的消融测试，用于探究不同上下文组件如何影响 Agent 的行为与表现。

主要特性

• 多提供方支持：兼容 SiliconFlow（Qwen）、豆包（字节跳动）、Kimi（Moonshot）以及 DeepSeek
• 多工具 Agent：PDF 解析、汇率换算、数值计算、Python 代码执行
• 多种上下文模式：五种上下文配置，用于消融实验
• 交互与批量模式：可运行单个任务，也可运行完整测试套件
• 会话历史：在一个会话中跨多次查询保持上下文
• 详尽分析：性能指标、可视化图表与综合报告

🤖 支持的 LLM 提供方

豆包（字节跳动）— 默认

• 模型：doubao-seed-1-6-thinking-250715（可自定义）
• API：通过火山引擎提供，兼容 OpenAI 接口
• 适用场景：进阶推理、响应更快，中英文任务皆宜

SiliconFlow

• 模型：Qwen/Qwen3.5-397B-A17B（可自定义）
• API：兼容 OpenAI 接口
• 适用场景：复杂推理任务、细致分析

Kimi（Moonshot AI）

• 模型：kimi-k3（K3 推理模型；temperature 强制为 1，max_tokens 需给足以容纳其思考输出）
• API：通过 Moonshot 平台提供，兼容 OpenAI 接口
• 适用场景：进阶推理、多轮对话，中英文任务皆宜
• 特性：支持上下文缓存，用于优化成本

DeepSeek

• 模型：deepseek-v4-flash（默认；更强档位可用 --model deepseek-v4-pro）
• API：通过 DeepSeek Platform 提供，兼容 OpenAI 接口
• 适用场景：高性价比的工具调用 Agent；启用思考模式，便于 no_reasoning 消融时剥离 reasoning_content
• 注意：旧别名 deepseek-chat / deepseek-reasoner 已弃用（2026-07-24）；推荐使用 V4 系列 id

🏗️ 架构

上下文组件

1. 完整上下文（Full Context）— 包含全部组件的完整 Agent
2. 无历史（No History）— 缺少历史工具调用记录
3. 无推理（No Reasoning）— 没有策略规划
4. 无工具调用（No Tool Calls）— 无法执行外部工具
5. 无工具结果（No Tool Results）— 看不到工具执行结果

可用工具

• parse_pdf(url) — 下载并提取 PDF 文档中的文本
• convert_currency(amount, from, to) — 实时汇率换算
• calculate(expression) — 简单数学表达式求值
• code_interpreter(code) — 执行 Python 代码，完成复杂计算、求和与数据处理

📋 前置条件

• Python 3.8+
• 任一支持提供方的 API Key：
  • SiliconFlow：从 SiliconFlow 获取
  • 豆包（字节跳动）：从 火山引擎 获取
  • Kimi（Moonshot）：从 Moonshot 平台 获取
  • DeepSeek：从 DeepSeek 平台 获取

📝 示例任务

系统内置 5 个预设示例任务，展示不同能力：

1. 简单汇率换算 — 基础多币种计算
2. 多币种预算分析 — 跨办公室的复杂开支分析
3. PDF 财务分析 — 解析并分析财务文档
4. 投资增长计算 — 复利计算结合汇率换算
5. 综合财务报告 — 综合使用全部工具的完整工作流

这些示例旨在展示 Agent 的能力以及上下文消融带来的影响。

🚀 快速开始

1. 安装

# Clone the repository
cd projects/week1/context

# Install dependencies
pip install -r requirements.txt

# Copy and configure environment
cp env.example .env
# Edit .env and add your API key (SILICONFLOW_API_KEY or ARK_API_KEY)
​

2. 配置提供方

# For Doubao (ByteDance) - Default
export ARK_API_KEY=your_key_here
python main.py  # Uses Doubao by default

# For SiliconFlow (Qwen)
export SILICONFLOW_API_KEY=your_key_here
python main.py --provider siliconflow

# For Kimi (Moonshot)
export MOONSHOT_API_KEY=your_key_here
python main.py --provider kimi

# For DeepSeek
export DEEPSEEK_API_KEY=your_key_here
python main.py --provider deepseek
# Optional stronger model:
python main.py --provider deepseek --model deepseek-v4-pro

# Or specify a custom model
python main.py --model doubao-seed-1-6-thinking-250715

# Universal OpenRouter fallback: if the provider key above is missing/invalid
# but OPENROUTER_API_KEY is set, requests are routed through OpenRouter and the
# model id is mapped automatically (bare gpt-*/o1-* -> openai/*, claude-* ->
# anthropic/*, deepseek-* -> deepseek/*, other native ids -> OPENROUTER_MODEL
# or openai/gpt-5.6-luna).
export OPENROUTER_API_KEY=sk-or-v1-your-key-here
python main.py                       # falls back to OpenRouter when ARK_API_KEY is unset
python main.py --provider openrouter # or use OpenRouter directly
​

3. 测试 Kimi / DeepSeek 集成

# Quick test of Kimi K3 model
export MOONSHOT_API_KEY=your_key_here
python test_kimi.py

# Use Kimi in main script
python main.py --provider kimi --mode interactive

# Run ablation study with Kimi
python main.py --provider kimi --mode ablation

# Quick test of DeepSeek V4
export DEEPSEEK_API_KEY=your_key_here
python test_deepseek.py
# or: python quick_test_deepseek.py

# Use DeepSeek in main script / ablation study
python main.py --provider deepseek --mode interactive
python main.py --provider deepseek --mode ablation
​

4. 运行交互模式（推荐）

# Default (Doubao)
python main.py --mode interactive

# With SiliconFlow provider
python main.py --mode interactive --provider siliconflow

# In interactive mode, you can:
# - Type 'samples' to see pre-defined tasks
# - Type 'sample 3' to test PDF parsing
# - Type 'providers' to list available providers
# - Type 'provider kimi' to switch providers
# - Type 'status' to see current configuration
# - Type 'help' for all commands
​

5. 运行示例任务

# Run without arguments to select from samples
python main.py --mode single

# With specific provider
python main.py --mode single --provider doubao

# Or provide your own task
python main.py --mode single \
  --task "Convert $1000 USD to EUR, GBP, and JPY. Calculate the average." \
  --context-mode full \
  --provider siliconflow
​

6. 运行消融实验

# With default provider (single case, all five context modes)
python main.py --mode ablation

# With Doubao provider
python main.py --mode ablation --provider doubao

# Multi-case comparison across modes (stronger evidence for the book's point)
python main.py --mode ablation --cases 3

# Compare only two modes and save raw results to a custom path
python main.py --mode ablation --ablation-modes full no_history --output my_ablation.json
​

main.py 是唯一的 CLI 入口。运行 python main.py --help 可查看完整的（中文）参数说明。

关键参数：

🧪 消融实验

消融实验会系统性地移除上下文中的各组件，以理解其重要性：

测试场景

一个复杂的财务分析任务，需要：

1. 解析 PDF 文档
2. 多次汇率换算
3. 数学计算
4. 汇总结果

预期行为

每种消融的具体实现（见 agent.py）：

• no_tool_calls — 请求中省略 tools 参数，模型没有可供调用的工具定义。
• no_tool_results — 每个工具结果都被替换为 [Tool result hidden] 占位符。
• no_reasoning — 每条 assistant 消息在加回轨迹之前，先剥离其中的 reasoning_content。
• no_history — _prepare_messages_for_api() 只向模型发送一个滑动窗口（系统提示 + 当前任务 + 最近一个 ReAct 步骤），因此早期步骤会被遗忘，Agent 倾向于重复调用工具。完整模式始终发送整条轨迹。

运行测试

# Run the full ablation study (single case, all five modes)
python main.py --mode ablation

# Run across multiple cases for a stronger comparison
python main.py --mode ablation --cases 3

# This will generate:
# - ablation_study_results.png (visualization, if matplotlib is installed)
# - ablation_study_report.md (detailed report)
# - ablation_results.json (raw data; override path with --output)
​

控制台会打印两张表：一张是每次运行的消融实验结果表，另一张是对比矩阵（上下文模式 × 用例），便于一眼读出各组件的效果。

📊 解读结果

性能指标

• 成功率：任务是否被正确完成
• 执行时间：完成任务的总耗时
• 迭代次数：Agent 与模型交互的轮数
• 工具调用数：外部工具被调用的次数
• 推理步数：策略规划迭代次数

输出示例

ABLATION STUDY RESULTS
================================================================================
| Test Name                      | Success | Time   | Iterations | Tool Calls |
|--------------------------------|---------|--------|------------|------------|
| Baseline - Full Context        | ✓       | 12.3s  | 5          | 8          |
| No Historical Tool Calls       | ✓       | 18.7s  | 8          | 12         |
| No Reasoning Process           | ✗       | 25.4s  | 10         | 15         |
| No Tool Call Commands          | ✗       | 3.2s   | 2          | 0          |
| No Tool Call Results           | ✗       | 15.6s  | 10         | 10         |
​

💡 关键洞见

1. 工具调用是根本

没有工具调用能力，Agent 无法与外部系统交互，任务根本无从完成。

2. 工具结果提供关键反馈

看不到结果时，Agent 等于盲走，会得出错误结论并陷入死循环。

3. 推理带来效率

策略规划能减少迭代次数与工具调用次数，同时提升速度与准确性。

4. 历史避免冗余

历史上下文能防止重复操作，并在多轮迭代中保持任务连贯性。

🛠️ 进阶用法

交互模式命令

交互模式支持以下命令：

注意： 提示符会用方括号显示当前提供方，例如 [KIMI]> 或 [DOUBAO]>。

会话历史

Agent 在整个交互会话中会保持会话历史：

• 持久上下文：Agent 会记住会话中此前的查询与回复
• 多轮对话：可以引用对话中较早出现的信息
• 工具调用记忆：此前的工具执行会被记住并可供引用
• 按需重置：使用 reset 命令可清空历史并重新开始

示例对话流程：

[DOUBAO]> Remember that our budget is $10,000. Calculate 15% of it.
# Agent calculates and remembers the budget

[DOUBAO]> Now convert that 15% amount to EUR
# Agent uses the previously calculated amount without re-asking

[DOUBAO]> What was our original budget?
# Agent recalls the $10,000 mentioned earlier
​

自定义任务

创建你自己的测试场景：

from agent import ContextAwareAgent, ContextMode

agent = ContextAwareAgent(api_key, ContextMode.FULL)
result = agent.execute_task("""
    Download the PDF from https://example.com/report.pdf,
    extract all monetary values, convert them to EUR,
    and calculate the total.
""")
​

创建测试 PDF

生成用于测试的示例 PDF：

python create_sample_pdf.py
# Creates test_pdfs/ directory with sample financial reports
​

配置

编辑 config.py 或设置环境变量：

export MODEL_TEMPERATURE=0.5
export MAX_ITERATIONS=15
export LOG_LEVEL=DEBUG
​

📁 项目结构

context/
├── agent.py              # Core agent implementation + context modes
├── main.py              # Single CLI entry point (single / ablation / interactive)
├── config.py            # Configuration management
├── create_sample_pdf.py # PDF generation utility
├── requirements.txt     # Dependencies
├── env.example         # Environment template
└── README.md           # This file
​

注意：消融实验位于 main.py（AblationTestSuite），通过
python main.py --mode ablation 运行。并不存在单独的 ablation_tests.py。

🔬 研究应用

本实现适用于：

• AI 安全研究：理解失败模式
• 系统设计：识别关键组件
• 优化：寻找最小可用配置
• 教学：讲授 Agent 架构原理

🤝 参与贡献

欢迎贡献！可改进的方向：

• 更多工具实现
• 更复杂的测试场景
• 其他的上下文消融策略
• 性能优化

⚠️ 局限性

• 汇率为固定值（生产环境应使用实时 API）
• 复杂排版下 PDF 解析可能失败
• 文档非常大时可能受模型 token 上限影响

📝 许可证

MIT License - 详情见 LICENSE 文件。

🙏 致谢

• SiliconFlow 提供 Qwen 模型 API
• DeepSeek 提供兼容 OpenAI 的 V4 API
• OpenAI 提供客户端库
• AI Agent 研究社区

📧 联系方式

如有疑问或反馈，请在 GitHub 上提 issue。

注意：这是一个演示 AI Agent 消融实验的教学项目。若用于生产环境，请实现完善的错误处理、限流与安全措施。