AI 服务 API

AI 服务 API 提供 AI 模型路由、提供商配置、用量计量和 Copilot 对话接口。

AI 路由

通用 AI 调用

POST /api/v1/ai/chat

通过 AI Router 发送请求，系统根据租户配置自动路由到合适的模型提供商。

请求体：

json

{
  "function": "copilot_chat",
  "messages": [
    {
      "role": "system",
      "content": "你是 NOLUX 智能助手，帮助用户进行电商数据分析和运营决策。"
    },
    {
      "role": "user",
      "content": "上个月天猫的 ROAS 是多少？"
    }
  ],
  "parameters": {
    "temperature": 0.7,
    "max_tokens": 2000
  }
}

请求字段说明：

字段	类型	必填	说明
`function`	string	是	功能类型，决定路由到哪个模型
`messages`	array	是	对话消息列表（OpenAI 兼容格式）
`parameters`	object	否	模型参数覆盖

功能类型（function）：

值	说明	默认模型
`copilot_chat`	Copilot 对话	Qwen-Max
`sentiment_analysis`	情感分析	Qwen-Plus
`keyword_mining`	关键词挖掘	Qwen-Turbo
`report_generation`	报告生成	Qwen-Max
`ad_optimization`	广告优化决策	Qwen-Max
`chatbi_query`	ChatBI 查询	Qwen-Plus

成功响应（200）：

json

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "chat-uuid-string",
    "function": "copilot_chat",
    "provider": "qwen",
    "model": "qwen-max",
    "response": {
      "role": "assistant",
      "content": "上个月天猫店铺的综合 ROAS 为 3.8，具体明细如下：\n- 直通车 ROAS：4.2\n- 引力魔方 ROAS：2.9\n- 品销宝 ROAS：5.1\n\n整体表现超出目标值 3.5，建议继续保持当前投放策略。"
    },
    "usage": {
      "input_tokens": 156,
      "output_tokens": 89,
      "total_tokens": 245
    },
    "latency_ms": 2340
  }
}

错误响应：

状态码	错误码	说明
403	`QUOTA_002`	AI Token 配额已用尽
503	`AI_001`	AI 服务暂时不可用
504	`AI_002`	AI 模型响应超时

流式响应

POST /api/v1/ai/chat/stream

与 /ai/chat 参数相同，但返回 SSE（Server-Sent Events）流式响应。

响应格式（SSE）：

data: {"delta": {"content": "上个月"}, "usage": null}

data: {"delta": {"content": "天猫店铺的"}, "usage": null}

data: {"delta": {"content": "综合 ROAS 为 3.8"}, "usage": null}

data: {"delta": null, "usage": {"input_tokens": 156, "output_tokens": 89}}

data: [DONE]

前端集成

流式响应使用标准 SSE 协议，前端可使用 EventSource 或 fetch + ReadableStream 接入。推荐使用流式模式以提升 Copilot 的对话体验。

提供商配置

获取提供商列表

GET /api/v1/ai/providers

获取当前租户配置的所有 AI 模型提供商。

成功响应（200）：

json

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": "uuid-string",
      "provider": "qwen",
      "display_name": "通义千问（默认）",
      "is_default": true,
      "is_active": true,
      "models": ["qwen-max", "qwen-plus", "qwen-turbo"],
      "created_at": "2026-01-15T00:00:00Z"
    },
    {
      "id": "uuid-string",
      "provider": "deepseek",
      "display_name": "DeepSeek V3",
      "is_default": false,
      "is_active": true,
      "models": ["deepseek-chat", "deepseek-reasoner"],
      "created_at": "2026-02-10T08:00:00Z"
    }
  ]
}

添加提供商

POST /api/v1/ai/providers

添加 BYOM 提供商（需 Growth 及以上方案）。

请求体：

json

{
  "provider": "deepseek",
  "display_name": "DeepSeek V3",
  "api_key": "sk-your-api-key",
  "base_url": "https://api.deepseek.com/v1",
  "models": ["deepseek-chat", "deepseek-reasoner"],
  "is_active": true
}

成功响应（201）：

json

{
  "code": 201,
  "message": "提供商添加成功",
  "data": {
    "id": "uuid-string",
    "provider": "deepseek",
    "display_name": "DeepSeek V3",
    "api_key_last4": "***key",
    "is_active": true,
    "created_at": "2026-03-14T10:30:00Z"
  }
}

连通性测试

POST /api/v1/ai/providers/{provider_id}/test

测试提供商的连通性和认证有效性。

成功响应（200）：

json

{
  "code": 200,
  "message": "连通性测试通过",
  "data": {
    "provider_id": "uuid-string",
    "results": {
      "endpoint_reachable": true,
      "auth_valid": true,
      "model_responsive": true,
      "latency_ms": 320,
      "first_token_latency_ms": 180
    },
    "tested_at": "2026-03-14T10:30:00Z"
  }
}

更新功能映射

PUT /api/v1/ai/function-mapping

配置各功能类型使用的模型提供商。

请求体：

json

{
  "mappings": [
    {
      "function": "copilot_chat",
      "primary_provider_id": "uuid-deepseek",
      "fallback_provider_id": "uuid-qwen"
    },
    {
      "function": "sentiment_analysis",
      "primary_provider_id": "uuid-qwen",
      "fallback_provider_id": null
    }
  ]
}

用量计量

获取用量统计

GET /api/v1/ai/usage

获取当前租户的 AI 用量统计。

查询参数：

参数	类型	必填	说明
`period`	string	否	统计周期：`today` / `this_week` / `this_month`（默认）
`group_by`	string	否	分组维度：`function` / `provider` / `user` / `day`

成功响应（200）：

json

{
  "code": 200,
  "message": "success",
  "data": {
    "period": "this_month",
    "summary": {
      "total_requests": 12580,
      "total_input_tokens": 3456789,
      "total_output_tokens": 1234567,
      "total_tokens": 4691356,
      "quota_limit": 5000000,
      "quota_usage_percent": 93.8,
      "total_cost_yuan": 46.91,
      "avg_latency_ms": 1850
    },
    "breakdown": [
      {
        "function": "copilot_chat",
        "requests": 5600,
        "tokens": 2100000,
        "avg_latency_ms": 2200
      },
      {
        "function": "sentiment_analysis",
        "requests": 3200,
        "tokens": 1500000,
        "avg_latency_ms": 1200
      }
    ]
  }
}

获取用量明细

GET /api/v1/ai/usage/details

获取逐条 AI 调用明细记录。

查询参数：

参数	类型	必填	说明
`page`	integer	否	页码
`page_size`	integer	否	每页条数
`function`	string	否	按功能类型筛选
`user_id`	string	否	按用户筛选
`date_from`	string	否	起始日期
`date_to`	string	否	结束日期

成功响应（200）：

json

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "req-uuid",
        "function": "copilot_chat",
        "provider": "qwen",
        "model": "qwen-max",
        "user_id": "user-uuid",
        "user_name": "张三",
        "input_tokens": 1250,
        "output_tokens": 680,
        "latency_ms": 2340,
        "status": "success",
        "created_at": "2026-03-14T10:30:00Z"
      }
    ],
    "total": 12580,
    "page": 1,
    "page_size": 20,
    "pages": 629
  }
}

Copilot 对话接口

创建对话会话

POST /api/v1/ai/copilot/sessions

创建一个新的 Copilot 对话会话。

请求体：

json

{
  "context": {
    "page": "/modules/ad-engine/campaigns",
    "selected_campaign_id": "campaign-uuid"
  }
}

成功响应（201）：

json

{
  "code": 201,
  "message": "会话创建成功",
  "data": {
    "session_id": "session-uuid",
    "context": {
      "page": "/modules/ad-engine/campaigns",
      "campaign_name": "直通车-护肤主推"
    },
    "created_at": "2026-03-14T10:30:00Z"
  }
}

发送消息

POST /api/v1/ai/copilot/sessions/{session_id}/messages

在会话中发送消息（支持流式响应）。

请求体：

json

{
  "content": "这个计划上周的表现怎么样？",
  "stream": true
}

非流式响应（200）：

json

{
  "code": 200,
  "message": "success",
  "data": {
    "message_id": "msg-uuid",
    "role": "assistant",
    "content": "直通车-护肤主推计划上周表现如下...",
    "actions": [
      {
        "type": "adjust_bid",
        "label": "提高出价 15%",
        "params": {"campaign_id": "xxx", "adjustment": 0.15},
        "requires_confirmation": true
      }
    ],
    "sources": [
      {"type": "campaign_data", "id": "campaign-uuid", "label": "计划数据"}
    ]
  }
}

actions 字段

当 AI 建议执行某个操作时，响应中会包含 actions 数组。前端可以渲染为可点击按钮，实现"一键执行"功能。

获取对话历史

GET /api/v1/ai/copilot/sessions/{session_id}/messages

获取对话会话的历史消息。

查询参数：

参数	类型	说明
`limit`	integer	返回最近 N 条消息，默认 50
`before`	string	返回此消息 ID 之前的消息（游标分页）

执行 AI 建议动作

POST /api/v1/ai/copilot/sessions/{session_id}/actions

执行 AI 建议的操作。

请求体：

json

{
  "message_id": "msg-uuid",
  "action_index": 0,
  "confirmed": true
}

成功响应（200）：

json

{
  "code": 200,
  "message": "操作执行成功",
  "data": {
    "action_id": "action-uuid",
    "type": "adjust_bid",
    "status": "completed",
    "result": {
      "campaign_id": "campaign-uuid",
      "old_bid": 2.50,
      "new_bid": 2.88,
      "adjustment": "+15%"
    },
    "executed_at": "2026-03-14T10:35:00Z"
  }
}

权限检查

执行动作前系统会验证当前用户是否有对应的操作权限。如权限不足，返回 403 PERM_001 错误。

AI 服务 API ​

AI 路由 ​

通用 AI 调用 ​

POST /api/v1/ai/chat ​

流式响应 ​

POST /api/v1/ai/chat/stream ​

提供商配置 ​

获取提供商列表 ​

GET /api/v1/ai/providers ​

添加提供商 ​

POST /api/v1/ai/providers ​

连通性测试 ​

POST /api/v1/ai/providers/{provider_id}/test ​

更新功能映射 ​

PUT /api/v1/ai/function-mapping ​

用量计量 ​

获取用量统计 ​

GET /api/v1/ai/usage ​

获取用量明细 ​

GET /api/v1/ai/usage/details ​

Copilot 对话接口 ​

创建对话会话 ​

POST /api/v1/ai/copilot/sessions ​

发送消息 ​

POST /api/v1/ai/copilot/sessions/{session_id}/messages ​

获取对话历史 ​

GET /api/v1/ai/copilot/sessions/{session_id}/messages ​

执行 AI 建议动作 ​

POST /api/v1/ai/copilot/sessions/{session_id}/actions ​

AI 服务 API

AI 路由

通用 AI 调用

POST /api/v1/ai/chat

流式响应

POST /api/v1/ai/chat/stream

提供商配置

获取提供商列表

GET /api/v1/ai/providers

添加提供商

POST /api/v1/ai/providers

连通性测试

POST /api/v1/ai/providers/{provider_id}/test

更新功能映射

PUT /api/v1/ai/function-mapping

用量计量

获取用量统计

GET /api/v1/ai/usage

获取用量明细

GET /api/v1/ai/usage/details

Copilot 对话接口

创建对话会话

POST /api/v1/ai/copilot/sessions

发送消息

POST /api/v1/ai/copilot/sessions/{session_id}/messages

获取对话历史

GET /api/v1/ai/copilot/sessions/{session_id}/messages

执行 AI 建议动作

POST /api/v1/ai/copilot/sessions/{session_id}/actions