{"repo": "13268305734/lmms-eval-source", "files": {"examples/README_API.md": {"83b71695b57b21328038b544c1ce944d8cf438aa": {"t": 1785674597.4234607, "n": 6438, "h": "d73866d1e27d1165", "c": "# API-based Model Evaluation Guide\n\n本指南介绍如何使用外部 API 调用模型进行测评，无需本地部署模型。\n\n## 快速开始\n\n### 基本用法\n\n```bash\n# 设置 API 配置\nexport EVAL_API_KEY=\"your-api-key\"\nexport EVAL_API_BASE=\"https://api.openai.com/v1\"\nexport EVAL_MODEL_NAME=\"gpt-4o\"\n\n# 运行评估\nbash run/eval_api.sh\n```\n\n### 使用不同的 API 进行测评和评判\n\n当需要测评模型和评判模型使用不同的 API 时：\n\n```bash\n# 测评模型 API（用于模型推理）\nexport EVAL_API_KEY=\"your-eval-api-key\"\nexport EVAL_API_BASE=\"https://api.openai.com/v1\"\nexport EVAL_MODEL_NAME=\"gpt-4o\"\n\n# 评判模型 API（用于 LLM-as-a-judge）\nexport JUDGE_API_KEY=\"your-judge-api-key\"\nexport JUDGE_API_BASE=\"https://api.deepinfra.com/v1/openai\"\n\n# 运行评估\nbash run/eval_api.sh\n```\n\n## 配置说明\n\n### 环境变量\n\n#### 测评模型配置（必需）\n\n| 变量 | 说明 | 示例 |\n|------|------|------|\n| `EVAL_API_KEY` | 测评模型的 API 密钥 | `sk-...` |\n| `EVAL_API_BASE` | 测评模型的 API 基础 URL | `https://api.openai.com/v1` |\n| `EVAL_MODEL_NAME` | 模型名称/版本 | `gpt-4o`, `Qwen/Qwen2.5-VL-7B-Instruct` |\n\n#### 评判模型配置（可选）\n\n| 变量 | 说明 | 默认值 |\n|------|------|--------|\n| `JUDGE_API_KEY` | 评判模型的 API 密钥 | 使用 `EVAL_API_KEY` |\n| `JUDGE_API_BASE` | 评判模型的 API 基础 URL | 使用 `EVAL_API_BASE` |\n\n**注意**: 如果未设置评判模型配置，将使用测评模型的配置。\n\n#### 评估配置（可选）\n\n| 变量 | 说明 | 默认值 |\n|------|------|--------|\n| `TASKS` | 评估任务列表 | `olympiadbench_physics_no_proof_all,phyx_mini,seephys` |\n| `BATCH_SIZE` | 批处理大小 | `128` |\n| `OUTPUT_PATH` | 输出路径 | `./logs` |\n| `CACHE_PATH` | 缓存路径 | `./cache` |\n| `VERBOSITY` | 日志详细程度 | `INFO` |\n| `ADDITIONAL_MODEL_ARGS` | 额外的模型参数 | 空 |\n\n### model_args 参数说明\n\n`--model_args` 接受逗号分隔的 `key=value` 格式参数。对于 `local_api_compatible` 模型，支持的参数包括：\n\n| 参数 | 说明 | 默认值 | 示例 |\n|------|------|--------|------|\n| `model_version` | 模型名称/版本 | 必需 | `gpt-4o`, `Qwen/Qwen2.5-VL-7B-Instruct` |\n| `base_url` | API 基础 URL | 必需 | `https://api.openai.com/v1` |\n| `api_key` | API 密钥 | 可选（可用环境变量） | `sk-...` |\n| `timeout` | 请求超时时间（秒） | `10` | `30` |\n| `max_retries` | 最大重试次数 | `3` | `5` |\n| `max_size_in_mb` | 最大图片大小（MB） | `1` | `5` |\n| `batch_size` | 请求批处理大小 | `64` | `128` |\n\n### 使用示例\n\n#### 示例 1: 使用 OpenAI API\n\n```bash\nexport EVAL_API_KEY=\"sk-proj-...\"\nexport EVAL_API_BASE=\"https://api.openai.com/v1\"\nexport EVAL_MODEL_NAME=\"gpt-4o\"\nexport TASKS=\"phyx_mini,seephys\"\n\nbash run/eval_api.sh\n```\n\n#### 示例 2: 使用 DeepInfra API\n\n```bash\nexport EVAL_API_KEY=\"dD0KG9m51qpyyreMOzoZHG3z1BwvvtZv\"\nexport EVAL_API_BASE=\"https://api.deepinfra.com/v1/openai\"\nexport EVAL_MODEL_NAME=\"Qwen/Qwen2.5-VL-7B-Instruct\"\nexport TASKS=\"olympiadbench_physics_no_proof_all\"\n\nbash run/eval_api.sh\n```\n\n#### 示例 3: 测评和评判使用不同 API\n\n```bash\n# 测评模型：使用 OpenAI\nexport EVAL_API_KEY=\"sk-openai-key\"\nexport EVAL_API_BASE=\"https://api.openai.com/v1\"\nexport EVAL_MODEL_NAME=\"gpt-4o\"\n\n# 评判模型：使用 DeepInfra（更便宜）\nexport JUDGE_API_KEY=\"deepinfra-key\"\nexport JUDGE_API_BASE=\"https://api.deepinfra.com/v1/openai\"\n\n# 运行评估\nexport TASKS=\"phyx_mini,seephys\"  # 这些任务需要 LLM-as-a-judge\nbash run/eval_api.sh\n```\n\n#### 示例 4: 自定义模型参数\n\n```bash\nexport EVAL_API_KEY=\"your-key\"\nexport EVAL_API_BASE=\"https://api.openai.com/v1\"\nexport EVAL_MODEL_NAME=\"gpt-4o\"\n\n# 添加额外的模型参数\nexport ADDITIONAL_MODEL_ARGS=\"timeout=30,max_retries=5,batch_size=64\"\n\nbash run/eval_api.sh\n```\n\n#### 示例 5: 在 SLURM 集群上运行\n\n创建 `submit_api_eval.sh`:\n\n```bash\n#!/bin/bash\n#SBATCH --job-name=api_eval\n#SBATCH --time=24:00:00\n#SBATCH --partition=gpu\n#SBATCH --output=api_eval_%j.out\n\n# 设置 API 配置\nexport EVAL_API_KEY=\"your-api-key\"\nexport EVAL_API_BASE=\"https://api.openai.com/v1\"\nexport EVAL_MODEL_NAME=\"gpt-4o\"\nexport JUDGE_API_KEY=\"your-judge-key\"\nexport JUDGE_API_BASE=\"https://api.deepinfra.com/v1/openai\"\n\n# 设置评估任务\nexport TASKS=\"olympiadbench_physics_no_proof_all,phyx_mini,seephys\"\nexport OUTPUT_PATH=\"./results_${SLURM_JOB_ID}\"\n\n# 运行评估\nbash run/eval_api.sh\n```\n\n然后提交：\n\n```bash\nsbatch submit_api_eval.sh\n```\n\n## 支持的 API 提供商\n\n### OpenAI\n\n```bash\nexport EVAL_API_KEY=\"sk-...\"\nexport EVAL_API_BASE=\"https://api.openai.com/v1\"\nexport EVAL_MODEL_NAME=\"gpt-4o\"  # 或 gpt-4-turbo, gpt-3.5-turbo 等\n```\n\n### DeepInfra\n\n```bash\nexport EVAL_API_KEY=\"your-deepinfra-key\"\nexport EVAL_API_BASE=\"https://api.deepinfra.com/v1/openai\"\nexport EVAL_MODEL_NAME=\"Qwen/Qwen2.5-VL-7B-Instruct\"  # 或其他支持的模型\n```\n\n### Azure OpenAI\n\n```bash\nexport EVAL_API_KEY=\"your-azure-key\"\nexport EVAL_API_BASE=\"https://your-resource.openai.azure.com/v1\"\nexport EVAL_MODEL_NAME=\"gpt-4\"\n```\n\n### 其他 OpenAI 兼容的 API\n\n任何兼容 OpenAI API 格式的服务都可以使用，只需设置相应的 `EVAL_API_BASE` 和 `EVAL_API_KEY`。\n\n## 任务配置\n\n### 需要 LLM-as-a-judge 的任务\n\n以下任务需要使用 LLM 作为评判器，需要配置 `JUDGE_API_KEY` 和 `JUDGE_API_BASE`：\n\n- `phyx_mini` - PhyX Mini 数据集\n- `seephys` - SeePhys 数据集\n- `hipho_*` - HiPhO 系列任务\n\n### 仅规则匹配的任务\n\n以下任务不需要 LLM-as-a-judge，只需要测评模型：\n\n- `olympiadbench_physics_no_proof_all` - OlympiadBench Physics\n\n### 组合任务\n\n```bash\n# 规则评估 + LLM-as-a-judge\nexport TASKS=\"olympiadbench_physics_no_proof_all,phyx_mini,seephys\"\n\n# 仅 LLM-as-a-judge 任务\nexport TASKS=\"phyx_mini,seephys,hipho_ipho_2025\"\n```\n\n## 常见问题\n\n### 1. API 密钥未设置\n\n**错误**: `Error: EVAL_API_KEY is not set`\n\n**解决**: 设置环境变量\n```bash\nexport EVAL_API_KEY=\"your-api-key\"\n```\n\n### 2. API 调用失败\n\n**问题**: API 请求返回错误\n\n**解决**:\n- 检查 API 密钥是否正确\n- 检查 API 基础 URL 是否正确\n- 查看 API 提供商的速率限制\n- 检查网络连接\n\n### 3. 评判 API 未配置\n\n**警告**: `Tasks require LLM-as-a-judge, but JUDGE_API_BASE or JUDGE_API_KEY is not set`\n\n**解决**: 如果任务需要 LLM-as-a-judge，设置评判 API：\n```bash\nexport JUDGE_API_KEY=\"your-judge-key\"\nexport JUDGE_API_BASE=\"https://api.example.com/v1\"\n```\n\n### 4. 模型名称错误\n\n**问题**: API 返回模型不存在的错误\n\n**解决**: 检查模型名称是否正确，不同 API 提供商支持的模型名称可能不同：\n- OpenAI: `gpt-4o`, `gpt-4-turbo`, `gpt-3.5-turbo`\n- DeepInfra: `Qwen/Qwen2.5-VL-7B-Instruct`, `meta-llama/Llama-3.1-70B-Instruct`\n\n### 5. 超时错误\n\n**问题**: 请求超时\n\n**解决**: 增加超时时间\n```bash\nexport ADDITIONAL_MODEL_ARGS=\"timeout=60\"\n```\n\n### 6. 速率限制\n\n**问题**: API 返回速率限制错误\n\n**解决**:\n- 降低批处理大小: `export BATCH_SIZE=64`\n- 增加重试次数: `export ADDITIONAL_MODEL_ARGS=\"max_retries=10\"`\n- 使用不同的 API 密钥或升级 API 计划\n\n## 性能优化\n\n1. **批处理大小**: 根据 API 提供商的限制调整 `BATCH_SIZE`\n2. **并发控制**: 某些 API 提供商对并发请求有限制\n3. **缓存**: 启用缓存可以避免重复请求\n4. **成本优化**: \n   - 使用更便宜的 API 进行评判（如 DeepInfra）\n   - 使用更强大的 API 进行测评（如 OpenAI）\n\n## 输出文件\n\n评估完成后，结果保存在 `OUTPUT_PATH` 目录下：\n\n- `results.json`: 评估结果汇总\n- `samples_*.jsonl`: 每个样本的详细结果\n- `config.yaml`: 评估配置\n\n## 与本地模型评估的对比\n\n| 特性 | API 评估 | 本地模型评估 |\n|------|----------|--------------|\n| 需要 GPU | ❌ | ✅ |\n| 需要 vLLM | ❌ | ✅ |\n| 设置复杂度 | 低 | 高 |\n| 成本 | API 费用 | 计算资源 |\n| 灵活性 | 高（可切换模型） | 低（需重新部署） |\n| 延迟 | 网络延迟 | 本地延迟 |\n\n## 最佳实践\n\n1. **分离测评和评判 API**: 使用更便宜的 API 进行评判，节省成本\n2. **使用缓存**: 启用缓存避免重复请求\n3. **监控 API 使用**: 跟踪 API 调用次数和成本\n4. **错误处理**: 脚本已包含基本的错误检查\n5. **日志记录**: 使用 `VERBOSITY=DEBUG` 获取详细日志\n\n"}}}}