eval_752
  • 简体中文

      • 后端配置指南

      更新日期：2026-03-13

      本指南说明 eval_752 目前有哪些配置保留在 .env，以及哪些运行参数已经迁移到 UI 和数据库。

      1. .env 中保留的变量

      这些变量仍然属于启动拓扑、基础设施或构建层配置，不能放到工作区 UI 里。

      1.1 基础变量

      变量默认值说明
      APP_NAMEeval_752服务名，写入日志与元数据。
      APP_ENVdevelopment环境标签（development / staging / production）。
      APP_LOG_LEVELINFO后端默认日志级别。
      DATABASE_URL必填PostgreSQL 连接串，例如 postgresql+psycopg://user:pass@host:5432/eval752。
      REDIS_URL必填Redis 连接串，供 Celery、事件流与缓存使用。

      注意：.env 文件不会递归展开变量。请不要在 DATABASE_URL 中写 :${POSTGRES_PASSWORD} 这类占位表达式；应直接填写字面值，并与 POSTGRES_PASSWORD 保持一致。

      1.2 Celery / Worker 拓扑

      变量默认值说明
      CELERY_BROKER_URL空留空时回退到 REDIS_URL。
      CELERY_RESULT_BACKEND空留空时回退到 REDIS_URL。
      RUN_RETRY_POLL_INTERVAL_SECONDS30Celery beat 轮询 runs.retry_stalled 的周期。

      1.3 运行引擎与特性开关

      变量默认值说明
      LITELLM_BACKENDlitellm预留给 SDK 适配层的后端切换。当前主路径使用 litellm。
      ARENA_ENABLEDtrueArena 功能入口开关。

      1.4 外部数据与密钥

      变量默认值说明
      HF_TOKEN空访问私有 Hugging Face 数据集时使用。
      HF_CACHE_DIR空自定义 Hugging Face 缓存目录。
      ENCRYPTION_KEY必填32 字节十六进制密钥，用于加密 Provider API Keys。用 openssl rand -hex 32 生成。

      1.5 Docker Compose 便利变量

      变量默认值说明
      POSTGRES_DBeval752Compose 默认数据库名。
      POSTGRES_USEReval752Compose 默认数据库用户。
      POSTGRES_PASSWORDchange-meCompose 默认数据库密码。必须与 DATABASE_URL 中的密码一致。

      1.6 前端构建 / 代理

      变量默认值说明
      VITE_API_BASE_URL/api浏览器里发出的 API Base。/api 表示由前端容器或反向代理继续转发。
      BACKEND_ORIGINhttp://backend:8000仅前端预览代理使用，用来决定 /api/* 转发到哪里。
      HEALTH_CHECK_TIMEOUT_SECONDS300CI / Compose 冒烟等待窗口。

      2. 已迁移到 UI + 数据库的工作区运行参数

      这些值现在通过 Settings → Workspace runtime controls 进行修改，并保存在数据库中。 修改后会作用于新的 provider smoke test、未来创建的新 run，以及后续 judge / worker completion 调用，不再要求你编辑 .env。

      UI 控制项说明
      Request timeout单次 completion 请求的总墙钟超时。
      Max completion tokens单题 completion 上限；留空表示交给 provider 默认行为。
      Completion retriescompletion 客户端的重试次数。
      Completion retry backoffcompletion 重试的基础退避秒数。
      Run recovery attemptsworker 自动恢复卡住 run 的最大次数。
      Run recovery delay重新调度卡住 run 前的等待秒数。
      Run recovery batch sizebeat 每轮最多重排多少个卡住 run。
      Cancellation check intervalworker 每处理多少题重新检查一次取消状态。
      Cancellation cache TTLRedis 中取消状态缓存的 TTL。
      Use LightEval executor是否让未来 run 走 LightEval 执行路径。

      这些值在数据库中没有记录时，会先回退到后端内置默认值。.env.example 已不再把它们暴露给普通部署路径。

      3. 不再支持的旧变量

      以下旧变量已经被彻底移除，若仍出现在 .env 或 shell 环境里，后端会在启动时直接失败：

      • LITELLM_MODE
      • LITELLM_STUB_FAIL_ONCE
      • LITELLM_STUB_ALWAYS_FAIL

      4. 使用方式

      1. 复制模板：cp .env.example .env
      2. 生成 ENCRYPTION_KEY：openssl rand -hex 32
      3. 修改 .env 中的基础设施变量，尤其是数据库密码与连接串
      4. 启动堆栈后，从 UI 完成以下工作：
        • 在 Providers 页面添加真实 provider
        • 在 Datasets 页面导入或构建数据集
        • 在 Settings 页面调整工作区运行策略

      5. GitHub Actions / Secrets 建议

      在 CI/CD 中，以下变量通常通过 Secret 或部署平台配置注入：

      • DATABASE_URL
      • REDIS_URL
      • ENCRYPTION_KEY
      • HF_TOKEN（若需要访问私有数据集）
      • POSTGRES_PASSWORD（如使用 Compose）

      工作区运行参数应通过产品内的 Settings 持久化，而不是通过 CI Secret 长期覆盖。

      6. 文档同步

      配置变更时请同步更新以下位置：

      • backend/src/eval_752/app/config.py
      • .env.example
      • 本文档

      如果某项配置改成了 UI 持久化控制，也应同步更新 Settings 页面文案和相关验收文档。