内容
# 上下文运行时
**适用于多款应用的高效优化器** — 面向LLM上下文的数据库查询规划器。应用程序说 *"我需要一个答案"*；运行时决定模型看到什么 — 调用什么、压缩什么、路由什么、验证什么 — 发出可检查、可重放的计划，并**从结果中学习**。它为AI上下文做的事情类似于查询规划器为SQL所做的事情。参见 [POSITIONING.md](./POSITIONING.md) 了解更多信息。
它可以优化任何具有以下条件的应用程序：（a）关于使用哪个上下文/配置的决策点；（b）可衡量的结果。目前已有11个租户已上线且运行正常（每个数字都是其`examples/<tenant>.py`中打印的学习奖励与基线奖励的比较）：
| 租户 | 上下文运行时调整 | 结果 |
|---|---|---|
| **sidekick** | 调用哪些技能 · 预算 | `SkillStore`的替换；**67% vs 33%** 基线接受率 |
| **redevops-rag** | 每个查询的`pool · limit · threshold · rerank …` | `ContextRuntimeRetrieverTuner`；**0.773 vs 0.323** 固定默认值 |
| **edge-sentinel (SOC)** | 每个警报要拉取的来源（CrowdSec · threat-intel · EDR） | 工具使用 + 批准门控；**0.900 vs 0.800** 始终完全基线 |
| **growth-engine** | 每个引流查询的归因窗口 + 源包 | **7.851 vs 5.282** 固定窗口 |
| **control-tower** | 每个“询问任何问题”的Metabase查询集 | **5.326 vs 1.643** 核心查询集 |
| **agentic-billing** | 每个账户要拉取的使用/发票/催收信号 | **4.122 vs 2.442** 全栈 |
| **social-autopilot** | 每个目标的频道/时机/内容策略 | **3.875 vs 0.773** 固定策略 |
| **agentic-support** | 每个工单要检索的KB/工单/账户上下文 | **3.679 vs 2.394** 全上下文 |
| **agentic-books** | 每个账簿问题要拉取的账本/报告 | **3.632 vs 2.430** 全账簿 |
| **market-radar** | 每个情报问题要扫描的竞争对手监视 | **3.611 vs 0.403** 全扫描 |
| **agentic-compliance** | 每个发现要拉取的规则家族证据 | **3.562 vs 2.463** 全证据 |
```bash
PYTHONPATH=. python examples/sidekick_learning.py # 离散策略强盗
PYTHONPATH=. python examples/rag_tuning.py # 数值旋钮调优
PYTHONPATH=. python examples/soc_triage.py # 工具使用网络安全租户
```
此外，还有 **ToolPlugin** 接口（`context_runtime/tools/` — 计划如何到达外部系统，具有批准门控审计跟踪）和 **trace导出器**（`context_runtime/observability/exporters.py` — JSONL离线，或Langfuse / OpenLLMetry-OTel，当安装额外功能时）。
> 状态：**v0.1垂直切片**。它完全离线运行，带有存根插件；真正的[redevops-rag](https://github.com/redevops-io/redevops-rag)检索和LiteLLM模型绑定已连接并延迟导入。参见 [SPEC.md](./SPEC.md) §10，了解这些测试所断言的一致性检查列表。
## 安装
```bash
pip install -e . # 核心（离线存根路径，零重依赖）
pip install -e ".[litellm]" # 跨100+提供商的真实模型
pip install -e ".[rag]" # redevops-rag — 单跳混合检索
pip install -e ".[hipporag]" # HippoRAG — 多跳图检索（规划器按查询选择）
```
**单跳 vs 多跳是按查询决定的。** 规划器分类意图并路由：当答案在一个块中时使用BM25/混合（redevops-rag），**当答案在文档之间的连接中时使用图（HippoRAG）** — 并且只有在需要时，成本模型才会支付图溢价。`python examples/hop_routing.py` 显示单跳遗漏了多跳表面化的桥接文档。
## 30秒导览
```python
from context_runtime import ContextRuntime, SourceRef
rt = ContextRuntime.default(docs) # 离线：存根模型 + 内存存储
# 运行 — 核心抽象（计划 → 构建上下文 → 执行 → 验证）
res = rt.run("解释部署X为何失败",
sources=[SourceRef("docs", "docs")],
constraints={"max_cost_usd": 2.0, "require_citations": True})
print(res.answer, res.cost_usd, res.trace)
# 解释 — 调试计划类似SQL（添加analyze=True进行EXPLAIN ANALYZE）
ex = rt.explain("解释部署X为何失败")
print(ex.intent.bucket, len(ex.candidates), ex.chosen.score.total)
# 模拟 — 预测成本/延迟/令牌，带有置信区间，无需执行
sim = rt.simulate("解释部署X为何失败")
print(sim.expected_cost_usd, sim.expected_models, sim.based_on_samples)
```
或从CLI / 配置：
```bash
PYTHONPATH=. python examples/incident_review.py
context-runtime --corpus ./docs run "我们的事件处理流程是什么？"
context-runtime --config context_runtime.yaml explain --analyze "为什么部署X失败？"
```
## 已实现的功能（v0.1）
| 接口（SPEC） | v0.1 实现 | 真实绑定（延迟） |
|---|---|---|
| **规划器三元组**（意图/候选/优化器） | 规则表意图 → 候选生成 → 启发式成本模型 | — *(真正的新核心)* |
| **成本模型 + 统计数据** | `PlanScore` 加权效用 + `pg_statistic` 样式校准 | 学习/神经（v0.3+） |
| **优化器** | 背包/贪婪效用优于可行集 | OR-Tools CP-SAT（v0.2） |
| **执行图IR** | 带有分支/循环/回滚种类的线性图 | 完整形状（v0.4） |
| **调度器** | 拓扑排序波浪 | Dagster / 成本感知（v2） |
| **推理器** | `SingleShotReasoner` （一个模型） | 混合：计划-工作者-批评家（v0.3+） |
| **模型插件** | 离线 `StubModel` | **LiteLLM** + 原生成本分级路由 |
| **检索器/存储** | `InMemoryStore` （关键词） | **redevops-rag** （DuckDB+BM25+RRF+重排名） |
| **压缩** | sidekick `clip` 结构包 | LLMLingua-2 语义（v0.1 可选） |
| **验证器** | 引文/接地检查 | RAGAS / Instructor |
| **可观察性** | 进程内 `Trace` + JSON | OpenLLMetry → Langfuse |
| **计划缓存** | 空/始终丢失存根 | 语义缓存（v0.2） |
## 架构
决策层很薄；底层被重用。参见：
- [ARCHITECTURE.md](./ARCHITECTURE.md) — 分层设计和基于成本的优化器循环
- [SPEC.md](./SPEC.md) — 规范接口契约（六个插件接口、IR、跟踪、计划缓存键）
- [ROADMAP.md](./ROADMAP.md) — v0.1 → v2 分阶段，带有每个阶段的退出基准
## 测试
```bash
pip install -e ".[dev]" && pytest # 18 个测试；test_conformance.py == SPEC §10
```
MCP 市场