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
@@ -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