docs(api): 同步 /api/v1/chat/completions 的 OpenAPI 与同步响应

补充 Chat Completions 的兼容响应模型与路由注释，确保 /api/v1/chat/completions 按同步兼容格式返回并更新对应测试与 Swagger 文档。
2026-05-16 00:19:39 +08:00
parent 34c3251c6d
commit ae197a742f
7 changed files with 491 additions and 154 deletions
@@ -4000,26 +4000,27 @@
                        "BearerAuth": []
                    }
                ],
-                "description": "网关任务接口按 model 选择平台模型；/api/v1 路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
+                "description": "/api/v1/chat/completions 同步执行：stream=true 返回 text/event-stream SSE；stream=false 或未传返回兼容 JSON；该接口忽略 X-Async。",
                "consumes": [
                    "application/json"
                ],
                "produces": [
-                    "application/json"
+                    "application/json",
+                    "text/event-stream"
                ],
                "tags": [
                    "tasks"
                ],
-                "summary": "创建或执行 AI 任务",
+                "summary": "创建 Chat Completions",
                "parameters": [
                    {
                        "type": "boolean",
-                        "description": "true 时异步创建任务并返回 202",
+                        "description": "该接口忽略此参数",
                        "name": "X-Async",
                        "in": "header"
                    },
                    {
-                        "description": "AI 任务请求，字段随任务类型变化",
+                        "description": "Chat Completions 请求",
                        "name": "input",
                        "in": "body",
                        "required": true,
@@ -4032,13 +4033,7 @@
                    "200": {
                        "description": "OK",
                        "schema": {
-                            "$ref": "#/definitions/httpapi.CompatibleResponse"
-                        }
-                    },
-                    "202": {
-                        "description": "Accepted",
-                        "schema": {
-                            "$ref": "#/definitions/httpapi.TaskAcceptedResponse"
+                            "$ref": "#/definitions/httpapi.ChatCompletionCompatibleResponse"
                        }
                    },
                    "400": {
@@ -4161,7 +4156,7 @@
                        "BearerAuth": []
                    }
                ],
-                "description": "网关任务接口按 model 选择平台模型；/api/v1 路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
+                "description": "网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
                "consumes": [
                    "application/json"
                ],
@@ -4254,7 +4249,7 @@
                        "BearerAuth": []
                    }
                ],
-                "description": "网关任务接口按 model 选择平台模型；/api/v1 路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
+                "description": "网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
                "consumes": [
                    "application/json"
                ],
@@ -4653,7 +4648,7 @@
                        "BearerAuth": []
                    }
                ],
-                "description": "网关任务接口按 model 选择平台模型；/api/v1 路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
+                "description": "网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
                "consumes": [
                    "application/json"
                ],
@@ -4985,7 +4980,7 @@
                        "BearerAuth": []
                    }
                ],
-                "description": "网关任务接口按 model 选择平台模型；/api/v1 路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
+                "description": "网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
                "consumes": [
                    "application/json"
                ],
@@ -5452,7 +5447,7 @@
                        "BearerAuth": []
                    }
                ],
-                "description": "网关任务接口按 model 选择平台模型；/api/v1 路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
+                "description": "网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
                "consumes": [
                    "application/json"
                ],
@@ -5565,7 +5560,7 @@
                        "BearerAuth": []
                    }
                ],
-                "description": "网关任务接口按 model 选择平台模型；/api/v1 路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
+                "description": "网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
                "consumes": [
                    "application/json"
                ],
@@ -5658,7 +5653,7 @@
                        "BearerAuth": []
                    }
                ],
-                "description": "网关任务接口按 model 选择平台模型；/api/v1 路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
+                "description": "网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
                "consumes": [
                    "application/json"
                ],
@@ -5777,7 +5772,7 @@
                        "BearerAuth": []
                    }
                ],
-                "description": "网关任务接口按 model 选择平台模型；/api/v1 路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
+                "description": "网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
                "consumes": [
                    "application/json"
                ],
@@ -5976,7 +5971,7 @@
                        "BearerAuth": []
                    }
                ],
-                "description": "网关任务接口按 model 选择平台模型；/api/v1 路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
+                "description": "网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
                "consumes": [
                    "application/json"
                ],
@@ -6137,7 +6132,7 @@
                        "BearerAuth": []
                    }
                ],
-                "description": "网关任务接口按 model 选择平台模型；/api/v1 路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
+                "description": "网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
                "consumes": [
                    "application/json"
                ],
@@ -6230,7 +6225,7 @@
                        "BearerAuth": []
                    }
                ],
-                "description": "网关任务接口按 model 选择平台模型；/api/v1 路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
+                "description": "网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
                "consumes": [
                    "application/json"
                ],
@@ -6323,7 +6318,7 @@
                        "BearerAuth": []
                    }
                ],
-                "description": "网关任务接口按 model 选择平台模型；/api/v1 路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
+                "description": "网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或 SSE 流。",
                "consumes": [
                    "application/json"
                ],
@@ -6551,6 +6546,82 @@
                }
            }
        },
+        "httpapi.ChatCompletionChoice": {
+            "type": "object",
+            "properties": {
+                "finish_reason": {
+                    "type": "string",
+                    "example": "stop"
+                },
+                "index": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "message": {
+                    "$ref": "#/definitions/httpapi.ChatCompletionChoiceMessage"
+                }
+            }
+        },
+        "httpapi.ChatCompletionChoiceMessage": {
+            "type": "object",
+            "properties": {
+                "content": {
+                    "type": "string",
+                    "example": "Hello"
+                },
+                "role": {
+                    "type": "string",
+                    "example": "assistant"
+                }
+            }
+        },
+        "httpapi.ChatCompletionCompatibleResponse": {
+            "type": "object",
+            "properties": {
+                "choices": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/httpapi.ChatCompletionChoice"
+                    }
+                },
+                "created": {
+                    "type": "integer",
+                    "example": 1710000000
+                },
+                "id": {
+                    "type": "string",
+                    "example": "chatcmpl-123"
+                },
+                "model": {
+                    "type": "string",
+                    "example": "gpt-4o-mini"
+                },
+                "object": {
+                    "type": "string",
+                    "example": "chat.completion"
+                },
+                "usage": {
+                    "$ref": "#/definitions/httpapi.ChatCompletionUsage"
+                }
+            }
+        },
+        "httpapi.ChatCompletionUsage": {
+            "type": "object",
+            "properties": {
+                "completion_tokens": {
+                    "type": "integer",
+                    "example": 8
+                },
+                "prompt_tokens": {
+                    "type": "integer",
+                    "example": 12
+                },
+                "total_tokens": {
+                    "type": "integer",
+                    "example": 20
+                }
+            }
+        },
        "httpapi.ChatMessage": {
            "type": "object",
            "properties": {
@@ -92,6 +92,59 @@ definitions:
          $ref: '#/definitions/store.CatalogProvider'
        type: array
    type: object
+  httpapi.ChatCompletionChoice:
+    properties:
+      finish_reason:
+        example: stop
+        type: string
+      index:
+        example: 0
+        type: integer
+      message:
+        $ref: '#/definitions/httpapi.ChatCompletionChoiceMessage'
+    type: object
+  httpapi.ChatCompletionChoiceMessage:
+    properties:
+      content:
+        example: Hello
+        type: string
+      role:
+        example: assistant
+        type: string
+    type: object
+  httpapi.ChatCompletionCompatibleResponse:
+    properties:
+      choices:
+        items:
+          $ref: '#/definitions/httpapi.ChatCompletionChoice'
+        type: array
+      created:
+        example: 1710000000
+        type: integer
+      id:
+        example: chatcmpl-123
+        type: string
+      model:
+        example: gpt-4o-mini
+        type: string
+      object:
+        example: chat.completion
+        type: string
+      usage:
+        $ref: '#/definitions/httpapi.ChatCompletionUsage'
+    type: object
+  httpapi.ChatCompletionUsage:
+    properties:
+      completion_tokens:
+        example: 8
+        type: integer
+      prompt_tokens:
+        example: 12
+        type: integer
+      total_tokens:
+        example: 20
+        type: integer
+    type: object
  httpapi.ChatMessage:
    properties:
      content:
@@ -4800,14 +4853,14 @@ paths:
    post:
      consumes:
      - application/json
-      description: 网关任务接口按 model 选择平台模型；/api/v1 路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或
-        SSE 流。
+      description: /api/v1/chat/completions 同步执行：stream=true 返回 text/event-stream
+        SSE；stream=false 或未传返回兼容 JSON；该接口忽略 X-Async。
      parameters:
-      - description: true 时异步创建任务并返回 202
+      - description: 该接口忽略此参数
        in: header
        name: X-Async
        type: boolean
-      - description: AI 任务请求，字段随任务类型变化
+      - description: Chat Completions 请求
        in: body
        name: input
        required: true
@@ -4815,15 +4868,12 @@ paths:
          $ref: '#/definitions/httpapi.TaskRequest'
      produces:
      - application/json
+      - text/event-stream
      responses:
        "200":
          description: OK
          schema:
-            $ref: '#/definitions/httpapi.CompatibleResponse'
-        "202":
-          description: Accepted
-          schema:
-            $ref: '#/definitions/httpapi.TaskAcceptedResponse'
+            $ref: '#/definitions/httpapi.ChatCompletionCompatibleResponse'
        "400":
          description: Bad Request
          schema:
@@ -4854,7 +4904,7 @@ paths:
            $ref: '#/definitions/httpapi.ErrorEnvelope'
      security:
      - BearerAuth: []
-      summary: 创建或执行 AI 任务
+      summary: 创建 Chat Completions
      tags:
      - tasks
  /api/v1/files/upload:
@@ -4905,8 +4955,8 @@ paths:
    post:
      consumes:
      - application/json
-      description: 网关任务接口按 model 选择平台模型；/api/v1 路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或
-        SSE 流。
+      description: 网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible
+        路径同步返回兼容响应或 SSE 流。
      parameters:
      - description: true 时异步创建任务并返回 202
        in: header
@@ -4966,8 +5016,8 @@ paths:
    post:
      consumes:
      - application/json
-      description: 网关任务接口按 model 选择平台模型；/api/v1 路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或
-        SSE 流。
+      description: 网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible
+        路径同步返回兼容响应或 SSE 流。
      parameters:
      - description: true 时异步创建任务并返回 202
        in: header
@@ -5220,8 +5270,8 @@ paths:
    post:
      consumes:
      - application/json
-      description: 网关任务接口按 model 选择平台模型；/api/v1 路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或
-        SSE 流。
+      description: 网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible
+        路径同步返回兼容响应或 SSE 流。
      parameters:
      - description: true 时异步创建任务并返回 202
        in: header
@@ -5434,8 +5484,8 @@ paths:
    post:
      consumes:
      - application/json
-      description: 网关任务接口按 model 选择平台模型；/api/v1 路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或
-        SSE 流。
+      description: 网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible
+        路径同步返回兼容响应或 SSE 流。
      parameters:
      - description: true 时异步创建任务并返回 202
        in: header
@@ -5735,8 +5785,8 @@ paths:
    post:
      consumes:
      - application/json
-      description: 网关任务接口按 model 选择平台模型；/api/v1 路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或
-        SSE 流。
+      description: 网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible
+        路径同步返回兼容响应或 SSE 流。
      parameters:
      - description: true 时异步创建任务并返回 202
        in: header
@@ -5809,8 +5859,8 @@ paths:
    post:
      consumes:
      - application/json
-      description: 网关任务接口按 model 选择平台模型；/api/v1 路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或
-        SSE 流。
+      description: 网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible
+        路径同步返回兼容响应或 SSE 流。
      parameters:
      - description: true 时异步创建任务并返回 202
        in: header
@@ -5870,8 +5920,8 @@ paths:
    post:
      consumes:
      - application/json
-      description: 网关任务接口按 model 选择平台模型；/api/v1 路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或
-        SSE 流。
+      description: 网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible
+        路径同步返回兼容响应或 SSE 流。
      parameters:
      - description: true 时异步创建任务并返回 202
        in: header
@@ -5948,8 +5998,8 @@ paths:
    post:
      consumes:
      - application/json
-      description: 网关任务接口按 model 选择平台模型；/api/v1 路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或
-        SSE 流。
+      description: 网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible
+        路径同步返回兼容响应或 SSE 流。
      parameters:
      - description: true 时异步创建任务并返回 202
        in: header
@@ -6079,8 +6129,8 @@ paths:
    post:
      consumes:
      - application/json
-      description: 网关任务接口按 model 选择平台模型；/api/v1 路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或
-        SSE 流。
+      description: 网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible
+        路径同步返回兼容响应或 SSE 流。
      parameters:
      - description: true 时异步创建任务并返回 202
        in: header
@@ -6184,8 +6234,8 @@ paths:
    post:
      consumes:
      - application/json
-      description: 网关任务接口按 model 选择平台模型；/api/v1 路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或
-        SSE 流。
+      description: 网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible
+        路径同步返回兼容响应或 SSE 流。
      parameters:
      - description: true 时异步创建任务并返回 202
        in: header
@@ -6245,8 +6295,8 @@ paths:
    post:
      consumes:
      - application/json
-      description: 网关任务接口按 model 选择平台模型；/api/v1 路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或
-        SSE 流。
+      description: 网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible
+        路径同步返回兼容响应或 SSE 流。
      parameters:
      - description: true 时异步创建任务并返回 202
        in: header
@@ -6306,8 +6356,8 @@ paths:
    post:
      consumes:
      - application/json
-      description: 网关任务接口按 model 选择平台模型；/api/v1 路径返回任务受理结果，OpenAI-compatible 路径同步返回兼容响应或
-        SSE 流。
+      description: 网关任务接口按 model 选择平台模型；除 /api/v1/chat/completions 以外的 /api/v1 任务路径返回任务受理结果，OpenAI-compatible
+        路径同步返回兼容响应或 SSE 流。
      parameters:
      - description: true 时异步创建任务并返回 202
        in: header