# Agent API 使用文档

## 概述

本 API 为外部 agent 提供三个核心能力，用于与微调模型评估平台交互。

**基础 URL**: `http://localhost:8100/api/agent`

---

## 1. 查询模型列表

**接口**: `GET /api/agent/models`

**说明**: 获取已部署和可部署的模型列表，包含模型元数据。

**返回示例**:
```json
{
  "deployed_models": [
    {
      "model_id": "全品类_选题_dense",
      "model_name": "31品类-QWEN32B-v2-全参数微调",
      "base_model": "qwen32b",
      "status": "deployed",
      "port": 8101,
      "metadata": {
        "data_source": "31个数据集",
        "training_method": "full",
        "usage": "使用QWEN32B模型在31个品类数据集上进行全参数微调"
      }
    }
  ],
  "available_models": [
    {
      "model_id": "全品类_选题_moe",
      "model_name": "31品类-QWEN30B-MoE",
      "base_model": "qwen30b",
      "status": "available",
      "metadata": {
        "data_source": "31个数据集",
        "training_method": "lora",
        "usage": "MoE架构微调模型"
      }
    }
  ]
}
```

**使用示例**:
```bash
curl http://localhost:8100/api/agent/models
```

---

## 2. 部署模型

**接口**: `POST /api/agent/deploy`

**说明**: 请求部署指定模型，系统会自动分配 GPU 和端口。

**请求参数**:
```json
{
  "model_id": "全品类_选题_dense",
  "epoch": 3  // 可选：指定 checkpoint epoch
}
```

**返回示例**:
```json
{
  "deployment_id": "deploy_abc123def456",
  "message": "部署已启动"
}
```

**注意事项**:
- 部署是异步的，使用"查询模型列表"接口检查状态是否变为 "deployed"
- 如果不指定 `epoch`，将使用最新的 checkpoint
- 部署通常需要 1-3 分钟，取决于模型大小

**使用示例**:
```bash
curl -X POST http://localhost:8100/api/agent/deploy \
  -H "Content-Type: application/json" \
  -d '{"model_id": "全品类_选题_dense", "epoch": 3}'
```

---

## 3. 模型推理

**接口**: `POST /api/agent/inference`

**说明**: 向已部署的模型发送查询并获取响应。

**请求参数**:
```json
{
  "model_id": "全品类_选题_dense",
  "query": "写一篇关于美食的小红书笔记",
  "temperature": 0.7  // 可选：0.0-1.0，默认 0.7
}
```

**返回示例**:
```json
{
  "response": "今天去了一家超棒的川菜馆...",
  "tokens_generated": 156
}
```

**注意事项**:
- 模型必须已部署（status="deployed"）才能推理
- 无状态：每次请求独立，不保留对话历史
- 超时时间：120 秒
- 最大 tokens：2048

**使用示例**:
```bash
curl -X POST http://localhost:8100/api/agent/inference \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "全品类_选题_dense",
    "query": "写一篇关于旅行的笔记",
    "temperature": 0.8
  }'
```

---

## 错误处理

所有接口返回标准 HTTP 状态码：

- `200`: 成功
- `400`: 请求错误（无效的 model_id、缺少参数等）
- `404`: 模型未找到或未部署
- `500`: 服务器内部错误

错误响应格式:
```json
{
  "detail": "错误信息描述"
}
```

---

## 完整工作流示例

```bash
# 1. 查询可用模型
curl http://localhost:8100/api/agent/models

# 2. 部署模型
curl -X POST http://localhost:8100/api/agent/deploy \
  -H "Content-Type: application/json" \
  -d '{"model_id": "全品类_选题_dense"}'

# 3. 等待部署完成（检查状态）
curl http://localhost:8100/api/agent/models

# 4. 执行推理
curl -X POST http://localhost:8100/api/agent/inference \
  -H "Content-Type: application/json" \
  -d '{"model_id": "全品类_选题_dense", "query": "写美食笔记"}'
```

---

## MCP Skill 集成

将这些接口封装为 MCP tools：

1. **list_models**: 无需参数
2. **deploy_model**: 参数 `model_id`（必需）、`epoch`（可选）
3. **inference**: 参数 `model_id`（必需）、`query`（必需）、`temperature`（可选）

### Python 示例

```python
import requests

BASE_URL = "http://localhost:8100/api/agent"

def list_models():
    """查询模型列表"""
    response = requests.get(f"{BASE_URL}/models")
    return response.json()

def deploy_model(model_id: str, epoch: int = None):
    """部署模型"""
    data = {"model_id": model_id}
    if epoch:
        data["epoch"] = epoch
    response = requests.post(f"{BASE_URL}/deploy", json=data)
    return response.json()

def inference(model_id: str, query: str, temperature: float = 0.7):
    """模型推理"""
    data = {
        "model_id": model_id,
        "query": query,
        "temperature": temperature
    }
    response = requests.post(f"{BASE_URL}/inference", json=data)
    return response.json()
```