#LightEval 配置构建器

更新日期：2025-10-22

本说明文档介绍 LightEvalConfigService 的配置结构、字段映射以及如何在后端/任务执行中复用生成的 config.yaml。该服务位于 backend/src/eval_752/services/lighteval_config.py，是任务 P2-BE-008 的交付物。

#1. 使用场景

• Celery Runner：运行前，根据 Run 选择的 Provider/模型/采样参数生成 LightEval config.yaml，再通过 lighteval endpoint litellm --config ... --output-dir ... --save-details --use-chat-template 执行，并尝试把 details artifact 导回 RunItem。
• 导出/复现：在 .eval752.zip 中附带配置，确保离线运行 LightEval 时无需再次填写 Provider 信息。
• CLI/CI：开发者或 CI Pipeline 可直接读取生成的配置文件，调用 LightEval CLI 或 Python API。

#2. 数据来源

#3. config.yaml 结构

metadata:
  provider_id: "prov-1"
  provider_name: "Demo Provider"
  provider_type: "openai"
  model_name: "openai/gpt-4o-mini"
  run_id: "run-123"
  dataset_id: "ds-42"
  dataset_name: "MMLU"
model_parameters:
  - model_name: "openai/gpt-4o-mini"
    provider_type: "openai"
    base_url: "https://api.example.com/v1"
    api_key: "sk-***"          # 或者 api_key_env: "LITELLM_API_KEY"
    concurrent_requests: 6
    timeout: 120
    max_retries: 5
    capabilities:
      json_mode: true
generation_parameters:
  temperature: 0.7
  max_new_tokens: 512
  stop:
    - "</s>"
execution:
  endpoint: "litellm"
  use_chat_template: true

#3.1 metadata

• 描述 Provider、模型、运行与数据集。model_name 始终带有 LiteLLM provider 前缀（例如 openai/gpt-4o）。

#3.2 model_parameters

• 必填：model_name、provider_type、base_url。
• API Key：默认直接写入 api_key；若 include_api_key=False，则改为 api_key_env="LITELLM_API_KEY"，方便在容器/CI 中通过环境变量注入。
• 并发/重试：concurrent_requests 来自 Provider rate_limit（缺省时回落到服务默认值）；timeout、max_retries 优先从 Run 配置的 litellm section 读取（兼容字段：request_timeout/api_max_retry 等），否则使用默认值。
• capabilities：将 Provider capabilities 字段透传，供后续分析或 CLI 输出参考。

#3.3 generation_parameters

• 支持字段：temperature, top_p, top_k, max_new_tokens, stop/stop_sequences, presence_penalty, frequency_penalty, repetition_penalty, seed 等。
• 配置来源：优先读取 Run generation/sampling section，其次读取顶层同名字段。
• stop 字段会自动合并数组与单值，去重后输出。

#3.4 execution

• 固定 endpoint="litellm"。
• use_chat_template 默认 true，对应 LightEval CLI 的 --use-chat-template 参数，可通过服务构造函数覆写。

#4. Python API

from eval_752.services.lighteval_config import LightEvalConfigService

service = LightEvalConfigService()
config = service.build(
    provider=provider,
    model_name="gpt-4o-mini",
    api_key=decrypted_key,
    run_config=run.config,
    run_id=run.id,
    dataset_id=run.dataset_id,
    dataset_name="MMLU",
)

config_dict = config.to_dict()   # 用于 JSON/YAML 序列化
yaml_text = config.to_yaml()     # 需要安装 PyYAML

注意：若环境未安装 PyYAML，则调用 to_yaml() 会抛出异常；Celery 任务可根据部署需求自选 JSON 或 YAML 序列化方式。

#5. 集成建议

1. Celery Runner（后续任务 P2-BE-009 实现）：

   • 在执行前调用 LightEvalConfigService.build()，获取配置后写入临时文件或直接传给 LightEval Python API。
   • 按需将 config.yaml 存储至运行目录，并在运行结束后清理。
   • 将 YAML 路径记录在 Run 日志中，便于用户调试。

2. 导出 .eval752.zip：

   • 将 config.to_dict() 写入 run_config.yaml/json，随结果打包，以便用户在离线环境执行 lighteval endpoint litellm --config run_config.yaml --use-chat-template。

3. 密钥管理：

   • 通过已有的 decrypt_api_key 解密 Provider 密钥后注入。
   • 若配置写入磁盘，请在任务结束后尽快删除，避免密钥残留。

4. 缓存策略：

   • 对 Provider+模型+采样参数组合计算哈希，将配置暂存以减少重复工作（计划在 P2-BE-009 中实现）。

#6. 下一步

• P2-BE-009：将生成的配置用于实际 LightEval 调用，处理任务重试与日志记录。
• P2-QA-004：完善 CLI/Python API 合同测试，覆盖失败重试、--use-chat-template 等关键路径。
• 文档：参考《docs/testing/lighteval-interoperability-fixtures.md》了解 fixtures 结构与运行矩阵。

若配置结构或字段要求变更，请同步更新本文件、specs/3_tasks.md、specs/4_notes.md 以及相关单元测试。