testing-llm

大模型与 AI 测试模式

用于测试大模型集成、评估 AI 输出质量、模拟响应以实现确定性 CI，以及应用 Agentic 测试工作流（规划器、生成器、修复器）的模式和工具。三者中，只有修复器在此处保留了本地参考；规划器和生成器阶段属于 testing-e2e 技能。

快速参考

区域	文件	用途
规则	rules/llm-evaluation.md	DeepEval 质量指标、Pydantic 架构验证、超时测试
规则	rules/llm-mocking.md	模拟大模型响应、VCR.py 录制、自定义请求匹配器
参考	references/ork-delta.md	供应商文档未涵盖的内部规则：GEval 和 RAGAS API 修正、阈值方向、磁带路径、黄金数据集和延迟预算
参考	references/healer-agent.md	自动修复失败的测试（选择器、等待、动态内容）
参考	references/langfuse-v4.md	Langfuse Python SDK v4 跟踪和数据集运行，以及非零吞吐量断言
清单	checklists/llm-test-checklist.md	完整的大模型测试清单（设置、覆盖率、CI/CD）

上游内容覆盖范围（不要重复陈述）

DeepEval、RAGAS、VCR.py 和 Playwright 均有自己的文档。本技能仅包含 OrchestKit 的补充内容（references/ork-delta.md），以及 rules/ 和 checklists/ 中的内部规则子集。请改为获取下方的源文档，而不要期待此处提供这些材料。

主题	来源
完整的 DeepEval 指标目录和各指标的构造函数参数（内部阈值表和双指标快速入门仍保留在此文件、rules/llm-evaluation.md 和 checklists/llm-test-checklist.md 中）	https://deepeval.com/docs/metrics-introduction
GEval 自定义标准：evaluation_params、evaluation_steps、criteria（内部导入修正仍保留在 references/ork-delta.md 中）	https://deepeval.com/docs/metrics-llm-evals
HallucinationMetric 参数（内部 0.3 上限和方向相反警告仍保留在 references/ork-delta.md 中）	https://deepeval.com/docs/metrics-hallucination
RAGAS 指标目录（Faithfulness、LLMContextRecall、FactualCorrectness）	https://docs.ragas.io/en/stable/concepts/metrics/available_metrics/
EvaluationDataset 构造方式（版本 0.2 之后的字段名称说明仍保留在 references/ork-delta.md 中）	https://docs.ragas.io/en/stable/concepts/components/eval_dataset/
VCR.py 配置键（录制模式开关和标头筛选器等内部规则仍保留在 rules/llm-mocking.md 中）	https://vcrpy.readthedocs.io/en/latest/configuration.html
Playwright Planner 和 Generator Agent、init-agents CLI 及生成的文件（内部修复器子集仍保留在 references/healer-agent.md 中）	https://playwright.dev/docs/test-agents
生成的测试所用的 Playwright 语义定位器层级	testing-e2e 技能（rules/e2e-playwright.md）以及 https://playwright.dev/docs/locators
指标得分样本的置信区间	https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.t.html

何时使用此技能

• 测试调用大模型 API 的代码（OpenAI、Anthropic 等）
• 验证 RAG 流水线的输出质量
• 在 CI 中设置确定性大模型测试
• 构建带质量门槛的评估流水线
• 应用 Agentic 测试模式（规划 -> 生成 -> 修复）

大模型模拟快速入门

模拟大模型响应，以进行快速、确定性的单元测试：

from unittest.mock import AsyncMock, patch
import pytest

@pytest.fixture
def mock_llm():
    mock = AsyncMock()
    mock.return_value = {"content": "Mocked response", "confidence": 0.85}
    return mock

@pytest.mark.asyncio
async def test_with_mocked_llm(mock_llm):
    with patch("app.core.model_factory.get_model", return_value=mock_llm):
        result = await synthesize_findings(sample_findings)
    assert result["summary"] is not None

**关键规则：**绝不要在 CI 中调用在线大模型 API。单元测试使用模拟，集成测试使用 VCR.py。

DeepEval 质量快速入门

使用多维度指标验证大模型输出质量：

from deepeval import assert_test
from deepeval.test_case import LLMTestCase
from deepeval.metrics import AnswerRelevancyMetric, FaithfulnessMetric

test_case = LLMTestCase(
    input="What is the capital of France?",
    actual_output="The capital of France is Paris.",
    retrieval_context=["Paris is the capital of France."],
)

assert_test(test_case, [
    AnswerRelevancyMetric(threshold=0.7),
    FaithfulnessMetric(threshold=0.8),
])

库说明（DeepEval、RAGAS）

DeepEval 指标会在 include_reason=True 时，在数值评分旁提供 reason 字段，这样 CI 构建失败时就能获得可读的解释，无需再次调用大模型：

metric = AnswerRelevancyMetric(threshold=0.7, include_reason=True)
metric.measure(test_case)
print(metric.score, metric.reason)
# 0.62  "Response addresses the topic but omits the date asked for."

RAGAS 使用基于类的指标 API——实例化指标类并传入 EvaluationDataset。llm= 是可选的；省略它即可使用已配置的默认评分器：

from ragas import evaluate
from ragas.metrics import Faithfulness, LLMContextRecall

result = evaluate(
    dataset,
    metrics=[Faithfulness(), LLMContextRecall()],
)

提高最低版本要求：deepeval >= 4.0、ragas >= 0.4。

供应商文档未说明的内部规范（反向设置的 HallucinationMetric 阈值、gpt-5-mini 评分器默认值、95 percent 置信区间计算方法，以及延迟、质量门槛和截断数值）记录在 references/ork-delta.md 中。编写任一库的设置代码前，请先阅读该文档。

质量指标阈值

指标	阈值	用途
答案相关性	>= 0.7	回复切合问题
忠实度	>= 0.8	输出与上下文一致
幻觉	<= 0.3	不编造事实
上下文精确率	>= 0.7	检索到的上下文相关
上下文召回率	>= 0.7	检索到所有相关上下文

结构化输出验证

始终使用 Pydantic 模式验证大模型输出：

from pydantic import BaseModel, Field

class LLMResponse(BaseModel):
    answer: str = Field(min_length=1)
    confidence: float = Field(ge=0.0, le=1.0)
    sources: list[str] = Field(default_factory=list)

async def test_structured_output():
    result = await get_llm_response("test query")
    parsed = LLMResponse.model_validate(result)
    assert 0 <= parsed.confidence <= 1.0

用于集成测试的 VCR.py

录制并重放大模型 API 调用，以执行确定性的集成测试：

@pytest.fixture(scope="module")
def vcr_config():
    import os
    return {
        "record_mode": "none" if os.environ.get("CI") else "new_episodes",
        "filter_headers": ["authorization", "x-api-key"],
    }

@pytest.mark.vcr()
async def test_llm_integration():
    response = await llm_client.complete("Say hello")
    assert "hello" in response.content.lower()

Agent 测试工作流

用于端到端测试自动化的三 Agent 模式：

Planner -> specs/*.md -> Generator -> tests/*.spec.ts -> Healer (auto-fix)

1. 规划器：探索你的应用并生成 Markdown 测试计划。由 testing-e2e 技能（rules/e2e-ai-agents.md）负责；CLI 及其生成的文件 说明见 https://playwright.dev/docs/test-agents。

2. 生成器：将 Markdown 规范转换为 Playwright 测试，并针对运行中的应用验证选择器。 同样由 testing-e2e（rules/e2e-ai-agents.md）负责；它遵循的定位器阶梯见 testing-e2e rules/e2e-playwright.md。

3. 修复器（references/healer-agent.md）：自动重放失败用例、检查 DOM 并修补定位器／等待逻辑，以修复失败测试。每个测试最多尝试修复 3 次。

Agent 初始化仅支持 CLI（npx playwright init-agents）；没有对应的配置键。只有修复阶段保留本地参考，因为最多尝试 3 次以及不修改测试逻辑都是内部限制，而非供应商默认设置。

始终测试的边缘情况

对于每种大模型集成，都要覆盖以下路径：

• 空值／null 输入 —— 空字符串、None 值
• 长输入 —— 接近 token 限制时的截断行为
• 超时 —— 失败时开放还是关闭
• 模式违规 —— 无效的结构化输出
• 提示词注入 —— 抵御对抗性输入的能力
• Unicode —— 提示词和回复中的非 ASCII 字符

完整检查清单见 checklists/llm-test-checklist.md。

反模式

反模式	正确做法
在 CI 中调用在线大模型	单元测试使用模拟，集成测试使用 VCR
随机种子	使用固定种子或模拟回复
只评估单个指标	评估 3-5 个质量维度
不处理超时	始终在测试中设置 < 1s 的超时时间
硬编码 API 密钥	使用环境变量，并在 VCR 中过滤
只断言 is not None	模式验证 + 质量指标

相关技能

• ork:testing-unit — 单元测试基础、AAA 模式
• ork:testing-integration — AI 流水线的集成测试
• ork:golden-dataset — 评估数据集管理
• ork:testing-e2e 负责 Planner 和 Generator Agent 工作流，以及 Playwright 定位器阶梯
• ork:testing-perf 负责 references/ork-delta.md 中提及的延迟和负载预算