vllm_agent_strategy/README.md

# vLLM Agent Strategy

全新版 vLLM-only 智能体策略。目标是最大化验证成功数量：优先跑悬赏模型，其次 Promote 已入库模型，再复用别人已下载模型，最后才自己下载新模型。

## 优先级

1. `bounty` / 悬赏模型：最高优先级，默认可直接提交。
2. `promote`：已经在 ModelHub 入库/验证成功的模型。
3. `downloaded_by_others`：别人已经下载成功的模型。
4. `self_download`：自己下载，最多 8 个 active 下载任务。

任务粒度是 `model_id + gpu_type + engine`，而不是整个 model。`MAX_USER_TASKS` 默认 2000。

## 配置文件

不用每次手动设置一堆环境变量。复制示例配置：

```bash
copy config.example.json config.local.json
```

然后编辑 `config.local.json`，填入 token、用户信息、目标算力等配置。

默认会按顺序读取：

```text
config.local.json
config.json
```

也可以用环境变量指定配置文件：

```bash
set STRATEGY_CONFIG_FILE=D:\4paradigm\vllm_agent_strategy\config.local.json
```

环境变量仍然可用，并且优先级高于配置文件，适合临时覆盖：

```bash
set SUBMIT_DRY_RUN=false
```

重要配置：

```json
{
  "AUTH_TOKEN": "",
  "HF_TOKEN": "",
  "CONFTEST_API_TOKEN": "",
  "EMAIL": "",
  "USER_ID": "",
  "CONTRIBUTORS": "",
  "STRATEGY_ID": "",
  "SUBMIT_DRY_RUN": true,
  "TARGET_MACHINE_NAMES": "MTT S4000,Hygon K100,Kunlunxin P800"
}
```

如果平台实际字段不是 `strategyId`，改 `CONTEST_TASK_STRATEGY_FIELD` 即可。

## 本地 dry run

```bash
python -m scripts.init_db
python -m scripts.load_seed --file seeds/bounty_models.example.csv --origin manual_bounty
python -m scripts.dry_run_plan --limit 50
python -m scripts.smoke_check --no-submit
```

## 启动服务

```bash
python -m app.main
```

健康检查：

```text
GET /health -> {"status":"ok"}
```

## Docker

```bash
docker build -t vllm-agent-strategy:local .
docker run --rm -p 8080:8080 --env-file .env vllm-agent-strategy:local
```

## 平台部署

平台部署流程：

```text
推代码到 dev.modelhub.org.cn/Gitea
-> 打 tag
-> 调 agent_platform create 创建策略
-> 拿返回的 id 作为 STRATEGY_ID
-> 等构建 ready
-> deploy
-> logs 查看运行日志
```

### 1. 推代码并打 tag

把本目录作为策略仓库根目录推到 `dev.modelhub.org.cn`，确保仓库根目录有：

```text
Dockerfile
requirements.txt
app/
seeds/
scripts/
```

示例：

```bash
git init
git add .
git commit -m "Initial vLLM agent strategy"
git remote add origin https://dev.modelhub.org.cn/<user>/vllm_agent_strategy.git
git tag v1.0.0
git push origin main --tags
```

如果已有仓库，按实际分支名和远端地址调整。

### 2. 创建策略并获取 STRATEGY_ID

可以使用脚本：

```bash
python -m scripts.agent_platform_api create \
  --name vllm-agent-strategy \
  --repo-url https://dev.modelhub.org.cn/<user>/vllm_agent_strategy \
  --tag v1.0.0
```

脚本默认从 `AGENT_PLATFORM_TOKEN` 或 `AUTH_TOKEN` 读取 token，也可以显式传：

```bash
python -m scripts.agent_platform_api --token <TOKEN> create \
  --name vllm-agent-strategy \
  --repo-url https://dev.modelhub.org.cn/<user>/vllm_agent_strategy \
  --tag v1.0.0
```

返回 JSON 中的：

```text
id
```

就是 `STRATEGY_ID`。

### 3. 查看构建状态

```bash
python -m scripts.agent_platform_api get --strategy-id <STRATEGY_ID>
python -m scripts.agent_platform_api sync --strategy-id <STRATEGY_ID>
```

等状态变成：

```text
ready
```

### 4. 部署策略

```bash
python -m scripts.agent_platform_api deploy --strategy-id <STRATEGY_ID>
```

### 5. 查看日志

```bash
python -m scripts.agent_platform_api logs --strategy-id <STRATEGY_ID> --limit 100
```

### 6. 停止策略

```bash
python -m scripts.agent_platform_api stop --strategy-id <STRATEGY_ID>
```

### 7. 本地和平台 STRATEGY_ID 的区别

本地 dry-run 可以在 `config.local.json` 里填：

```json
"STRATEGY_ID": "local-dry-run"
```

平台部署时，平台会注入真实 `STRATEGY_ID` 环境变量。环境变量优先级高于配置文件。

## Agent Platform API helper

新增脚本：

```text
scripts/agent_platform_api.py
```

支持：

```bash
python -m scripts.agent_platform_api me
python -m scripts.agent_platform_api list
python -m scripts.agent_platform_api create --name ... --repo-url ... --tag ...
python -m scripts.agent_platform_api get --strategy-id ...
python -m scripts.agent_platform_api sync --strategy-id ...
python -m scripts.agent_platform_api deploy --strategy-id ...
python -m scripts.agent_platform_api logs --strategy-id ...
python -m scripts.agent_platform_api stop --strategy-id ...
python -m scripts.agent_platform_api delete --strategy-id ...
```

## GGUF / llamacpp

本版本只实现 vLLM。GGUF/llamacpp 后续可基于 `tasks.engine` 增加分支。