LLM Integration

中文 | English

LLM 集成与验证

维护版本：v0.51.2 ｜ 最后更新：2026-07-06

EnerOS 在 crates/eneros-ai 中提供 LlmClient trait 抽象与 LlmAgent 装饰器，支持 OpenAI / Anthropic / Ollama 三种后端，并在 v0.50.1 / v0.50.2 完成真实场景验证框架。本页概述集成接口与验证方法；完整决策请参阅 ADR-0017 与 ADR-0018。

LlmClient trait

#[async_trait]
pub trait LlmClient: Send + Sync {
    async fn complete(&self, prompt: &str) -> Result<String, LlmError>;
    fn model_name(&self) -> &str;
}

实现	crate 模块	后端	默认模型
OpenAiClient	eneros-ai::openai	OpenAI API	gpt-4o-mini
AnthropicClient	eneros-ai::anthropic	Anthropic API	claude-3-5-sonnet
OllamaClient	eneros-ai::ollama	本地 Ollama	qwen2.5:7b-instruct
MockLlmClient	eneros-test-utils	测试桩	—

LlmAgent 装饰器

pub struct LlmAgent<T: LlmClient> {
    client: T,
    prompt_template: PromptTemplate,
    parser: LlmDecisionParser,
}

impl<T: LlmClient> LlmAgent<T> {
    pub fn new(client: T, template: PromptTemplate) -> Self { /* ... */ }

    pub async fn decide(&self, ctx: &DecisionContext) -> Result<Vec<AgentAction>> {
        let prompt = self.prompt_template.render(ctx);
        let response = self.client.complete(&prompt).await?;
        self.parser.parse(&response)
    }
}

Prompt 模板

crates/eneros-ai/src/prompts/ 提供 7 种领域 Agent 的 Prompt 模板：

模板	用途	输入上下文	期望输出
dispatch	调度决策	负荷 / 发电 / 备用	机组组合 + 出力分配
forecast	负荷预测	历史时序 / 气象	未来 24h 负荷曲线
operation	操作执行	当前拓扑 / 告警	操作序列
planning	运行规划	检修计划 / 负荷预测	日前计划
trading	市场交易	电价 / 负荷预测	竞价曲线
self_healing	故障自愈	故障位置 / 拓扑	隔离 + 恢复策略
maintenance	设备维护	设备状态 / 历史告警	维护建议

v0.50.1 100 场景验证

tests/llm_verify/ 提供 100 个真实电力场景的预飞行 + mock 执行框架：

tests/llm_verify/
├── fixtures/           # 100 个场景 JSON（IEEE-14 拓扑 + 故障 + 负荷）
├── src/
│   ├── preflight.rs    # 场景预飞行（参数校验）
│   ├── mock_executor.rs# mock LLM 执行器
│   ├── harness.rs      # 测试骨架
│   ├── scenarios.rs    # 场景加载器
│   ├── metrics.rs      # C1-C4 指标计算
│   └── report.rs       # 验证报告生成
└── tests/
    └── llm_verify_100.rs

4 项硬指标

指标	含义	通过条件
C1	Action 一致性（Agent 动作类型与场景期望一致）	≥ 80%
C2	决策可审计性（决策可在审计日志中追溯）	100%
C3	违规检测率（违反安全约束的决策被检测）	100%
C4	时延合规（决策时延在预算内）	≥ 95%

注意：C1 排除 Self-Healing 场景，因为 SelfHealingAgent::handle_emergency 合法产生 EmergencyOverride 来自确定性管线。

v0.50.2 20 轮语义验证

tests/llm_verify_semantic_20/ 在 100 场景中抽取 20 个子集，加入语义正确性框架：

tests/llm_verify_semantic_20/
├── src/
│   ├── semantic.rs     # 11 条期望规则 + 3 维匹配
│   ├── recording_client.rs # RecordingLlmClient（录制 LLM 响应）
│   └── report.rs       # 语义报告
└── tests/
    └── llm_verify_semantic_20.rs

11 条期望规则

针对每个场景定义 11 条期望（如"必须断开故障支路"、"必须隔离故障区域"、"必须恢复非故障区域供电"等），通过 3 维匹配（关键词 / 数值 / 拓扑）评估。

RecordingLlmClient

录制 LLM 真实响应到 JSON 文件，便于离线重放与回归测试：

pub struct RecordingLlmClient<T: LlmClient> {
    inner: T,
    records: Vec<LlmRecord>,
}

真实 LLM 调用（用户侧）

测试框架默认使用 MockLlmClient 跳过真实调用。用户在本地有 Ollama + qwen2.5:7b-instruct 时可启用真实验证：

# 启动 Ollama
ollama pull qwen2.5:7b-instruct
ollama serve

# 运行 100 场景真实验证
cargo test --test llm_verify_100 --features llm_verify_real

# 运行 20 轮语义验证
cargo test --test llm_verify_semantic_20 --features llm_verify_real

无 Ollama 时测试通过预飞行探测优雅跳过（preflight_probe() → Ok(())），返回 "1 passed; 0 failed"。

已知限制（v0.51.2）

• 仅支持本地 Ollama，未集成云端 LLM 的真实调用测试
• 仅 IEEE-14 拓扑，未覆盖 IEEE 30/118
• 仅硬不变式（N-1 / 热稳 / 电压），未覆盖软约束
• 单次运行，未做多次取均值
• InMemoryAuditSink 不带 HMAC 链
• 未捕获 token 用量
• 语义匹配仅关键词，未做语义嵌入
• 7b 模型为下限，未在更大模型上验证
• 容许回退（permissive fallback），可能掩盖部分错误

相关文档

• ADR-0017 LLM 真实场景验证
• ADR-0018 LLM 语义验证
• Agent 运行时 — LlmAgent 在 7 种 Agent 中的应用
• SafetyGateway — LLM 决策的合规审计
• 主仓库 crates/eneros-ai/ — 源码
• 主仓库 tests/llm_verify/ — 验证框架