# Apipost 调用示例

本文档给出 `/query` 端点的一条完整 Apipost 调用示例,包含请求体、真实响应以及字段说明。
可直接复制到 Apipost(或 Postman、Insomnia)里执行;在 Apipost 中可使用 `导入 cURL`
把示例直接贴进去。

## 1. 环境准备

```bash
# 1) 启动 Milvus(任选一种)
docker compose up -d milvus
# 或:milvus-standalone docker 启动

# 2) 准备数据
python scripts/prepare_data.py
# SQLite 写入 ./data/workOrder.db(或 .env 中 SQLITE_DB_PATH 指定的位置)
# Milvus collection 写入 agentic_rag_docs

# 3) 启动 API
uvicorn app.main:app --host 0.0.0.0 --port 8000
```

验证服务可达:

```bash
curl -s http://localhost:8000/health
# {"status":"ok"}
```

## 2. Apipost 调用配置

| 字段 | 值 |
| --- | --- |
| Method | `POST` |
| URL | `http://localhost:8000/query` |
| Headers | `Content-Type: application/json` |
| Body | `raw / JSON` |

> Apipost 的「导入 cURL」直接粘下面的 curl 即可。

## 3. curl 请求

```bash
curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "今天上午阿里云 SSL-VPN 频繁断开,Windows 客户端提示认证超时。请统计过去 30 天同类故障发生次数,结合内部 VPN 排障手册和厂商官网最新服务公告,判断更可能是本地配置问题还是公共服务异常,并给出排查步骤。",
    "session_id": "apipost-demo-001",
    "debug": true
  }'
```

PowerShell 等价命令:

```powershell
$body = @{
  query      = "今天上午阿里云 SSL-VPN 频繁断开,Windows 客户端提示认证超时。请统计过去 30 天同类故障发生次数,结合内部 VPN 排障手册和厂商官网最新服务公告,判断更可能是本地配置问题还是公共服务异常,并给出排查步骤。"
  session_id = "apipost-demo-001"
  debug      = $true
} | ConvertTo-Json

Invoke-RestMethod -Method Post `
  -Uri "http://localhost:8000/query" `
  -ContentType "application/json" `
  -Body $body
```

## 4. 实际响应(完整 JSON)

下面是 `scripts/capture_apipost_example.py` 跑出来的真实响应,与生产路径下
`/query` 返回的字段结构、字段顺序、字段值一致(只是工具结果被 fixture 取代)。

```json
{
  "answer": "基于已检索证据，结论如下。\n- 历史工单：服务 aliyun_ssl_vpn 最近 30 天、错误类型为"auth_timeout" 且 客户端为"Windows"的工单共 2 起，其中已解决 2 起、仍需跟进 0 起；采取的解决方案包括：refresh_certificate(1 次)、reset_vpn_profile(1 次)。 [1]\n- 内部手册：Windows 客户端排查顺序：检查日志 → 验证证书 → 重建 Profile → 联系厂商。 [2]\n- 厂商公告：【示例夹具】阿里云 SSL-VPN 当前运行正常，无服务异常公告。 [3]\n- 综合判断：历史工单有可复现的本地处置记录(证书刷新/重建 Profile),厂商侧公告显示服务运行正常,倾向本地配置问题;请优先按内部手册步骤排查,公共服务异常可暂不升级。",
  "citations": [
    {
      "source_type": "milvus",
      "source": "vpn_troubleshooting.md",
      "content": "Windows 客户端排查顺序：检查日志 → 验证证书 → 重建 Profile → 联系厂商。",
      "score": 0.91,
      "knowledge_type": "internal_doc",
      "metadata": {
        "doc_type": "troubleshooting_guide",
        "service_name": "aliyun_ssl_vpn",
        "category": "Windows"
      }
    },
    {
      "source_type": "sql",
      "source": "incidents",
      "content": "服务 aliyun_ssl_vpn 最近 30 天、错误类型为"auth_timeout" 且 客户端为"Windows"的工单共 2 起，其中已解决 2 起、仍需跟进 0 起；采取的解决方案包括：refresh_certificate(1 次)、reset_vpn_profile(1 次)。",
      "score": null,
      "knowledge_type": "structured",
      "metadata": {
        "query_name": "summarize_recent_incidents",
        "service_name": "aliyun_ssl_vpn",
        "days": 30,
        "error_type": "auth_timeout",
        "client_os": "Windows",
        "incident_count": 2,
        "resolved_count": 2,
        "open_count": 0,
        "resolution_counts": {
          "refresh_certificate": 1,
          "reset_vpn_profile": 1
        },
        "incident_ids": ["INC1001", "INC1002"]
      }
    },
    {
      "source_type": "web",
      "source": "https://help.aliyun.com/zh/vpn/product-overview/notice/",
      "content": "【示例夹具】阿里云 SSL-VPN 当前运行正常，无服务异常公告。",
      "score": 0.95,
      "knowledge_type": "realtime",
      "metadata": {
        "title": "阿里云 VPN 网关动态与公告",
        "url": "https://help.aliyun.com/zh/vpn/product-overview/notice/",
        "published_date": null
      }
    }
  ],
  "route": {
    "needs_retrieval": true,
    "intent": "multi_source_diagnosis",
    "task_type": "diagnose",
    "routes": ["sql_query", "milvus_search", "web_search"],
    "knowledge_types": ["structured", "internal_doc", "realtime"],
    "requires_decomposition": true,
    "confidence": "high",
    "reason_code": "MULTIPLE_DATA_SOURCES_REQUIRED",
    "filters": {
      "service_name": "aliyun_ssl_vpn",
      "error_type": "auth_timeout",
      "client_os": "Windows",
      "days": 30
    },
    "max_rounds": 2,
    "fallback": "clarify"
  },
  "executed_queries": [
    {
      "step_id": "search_troubleshooting_doc",
      "tool": "milvus_search",
      "query": "aliyun_ssl_vpn auth_timeout 排查步骤 Windows",
      "arguments": {
        "service_name": "aliyun_ssl_vpn",
        "client_os": "Windows",
        "doc_type": "troubleshooting_guide",
        "top_k": 4
      },
      "status": "success",
      "latency_ms": 0
    },
    {
      "step_id": "query_incident_statistics",
      "tool": "sql_query",
      "query": "统计 aliyun_ssl_vpn 最近 30 天auth_timeout 的有效工单",
      "arguments": {
        "service_name": "aliyun_ssl_vpn",
        "error_type": "auth_timeout",
        "days": 30,
        "client_os": "Windows"
      },
      "status": "success",
      "latency_ms": 0
    },
    {
      "step_id": "search_vendor_status",
      "tool": "web_search",
      "query": "site:help.aliyun.com/zh/vpn 阿里云 SSL-VPN auth_timeout 运维事件 最新公告",
      "arguments": { "max_results": 3 },
      "status": "success",
      "latency_ms": 0
    }
  ],
  "trace": [
    {
      "node": "normalize_query",
      "at": "2026-08-02T14:26:54.680526+00:00",
      "detail": { "query": "今天上午阿里云 SSL-VPN 频繁断开,Windows 客户端提示认证超时。请统计过去 30 天同类故障发生次数,结合内部 VPN 排障手册和厂商官网最新服务公告,判断更可能是本地配置问题还是公共服务异常,并给出排查步骤。" }
    },
    {
      "node": "route_query",
      "at": "2026-08-02T14:26:54.680749+00:00",
      "detail": {
        "intent": "multi_source_diagnosis",
        "task_type": "diagnose",
        "routes": ["sql_query", "milvus_search", "web_search"],
        "knowledge_types": ["structured", "internal_doc", "realtime"],
        "reason_code": "MULTIPLE_DATA_SOURCES_REQUIRED",
        "filters": {
          "service_name": "aliyun_ssl_vpn",
          "error_type": "auth_timeout",
          "client_os": "Windows",
          "days": 30
        }
      }
    },
    {
      "node": "plan_query",
      "at": "2026-08-02T14:26:54.681038+00:00",
      "detail": {
        "steps": [
          {
            "id": "search_troubleshooting_doc",
            "tool": "milvus_search",
            "query": "aliyun_ssl_vpn auth_timeout 排查步骤 Windows",
            "arguments": { "service_name": "aliyun_ssl_vpn", "client_os": "Windows", "doc_type": "troubleshooting_guide", "top_k": 4 },
            "depends_on": []
          },
          {
            "id": "query_incident_statistics",
            "tool": "sql_query",
            "query": "统计 aliyun_ssl_vpn 最近 30 天auth_timeout 的有效工单",
            "arguments": { "service_name": "aliyun_ssl_vpn", "error_type": "auth_timeout", "days": 30, "client_os": "Windows" },
            "depends_on": []
          },
          {
            "id": "search_vendor_status",
            "tool": "web_search",
            "query": "site:help.aliyun.com/zh/vpn 阿里云 SSL-VPN auth_timeout 运维事件 最新公告",
            "arguments": { "max_results": 3 },
            "depends_on": []
          }
        ]
      }
    },
    {
      "node": "execute_plan",
      "at": "2026-08-02T14:26:54.681697+00:00",
      "detail": {
        "tools": ["milvus_search", "sql_query", "web_search"],
        "statuses": ["success", "success", "success"],
        "evidence_count": 3
      }
    },
    {
      "node": "grade_evidence",
      "at": "2026-08-02T14:26:54.681916+00:00",
      "detail": {
        "relevant": true,
        "sufficient": true,
        "missing_aspects": [],
        "conflict": true,
        "recommended_action": "accept",
        "reason": "证据完整但厂商公告与内部手册结论冲突，需在答案中并列两条路径。"
      }
    },
    {
      "node": "generate_answer",
      "at": "2026-08-02T14:26:54.682123+00:00",
      "detail": { "partial": false }
    }
  ],
  "termination_reason": "evidence_accepted"
}
```

## 5. 关键字段说明

| 字段 | 含义 |
| --- | --- |
| `answer` | 面向最终用户的自然语言结论,带 `[1] [2] [3]` 引用编号指向 `citations` |
| `citations[].source_type` | `sql` / `milvus` / `web` 三类证据源 |
| `citations[].knowledge_type` | `structured` / `internal_doc` / `realtime`,与 Schema 枚举对齐 |
| `route.routes` | 本次请求实际命中的工具集合,`multi_source_diagnosis` 时为 3 条 |
| `route.filters` | 从用户问题抽取出的结构化槽位(`service_name` / `error_type` / `client_os` / `days`) |
| `executed_queries` | 每个工具步骤的实际入参(仅 `debug=true` 时返回) |
| `trace` | LangGraph 各节点执行轨迹,便于回溯(仅 `debug=true` 时返回) |
| `termination_reason` | 终止原因:`evidence_accepted` / `vendor_evidence_missing` / `retrieval_budget_exhausted` / `clarification_required` / `security_policy` |

## 6. 复现这条响应

```bash
# 跑一次同样的 service.invoke,把 QueryResponse 直接打到 stdout
python scripts/capture_apipost_example.py
```

> 注:脚本不连真实 Milvus/Tavily,内部用 FakeVectorStore / FakeWebSearchProvider 复现
> LangGraph 完整执行流(包括 plan → execute → grade → generate),保证响应字段顺序、
> trace 时序、references 编号与生产路径完全一致。
