> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gemini 4 回顯模型不一致怎麼辦？

> Gemini 4 原生響應的 modelVersion 與請求模型不一致時，如何告警、記錄 responseId、隔離異常任務並生成第二批重跑清單。

## 簡短回答

呼叫 `gemini-4-argon`、`gemini-4-hydrogen` 等 Gemini 4 模型時，如果原生響應裡的 `modelVersion` 與請求模型不同，**不要只看 HTTP 200 就把任務記為成功，也不要立刻自動重試**。

建議保留這次響應，記錄請求模型、回顯模型、`responseId` 和業務任務 ID，將任務標記為 `needs_rerun`；整批結束後生成異常報告，再決定是否只對這批任務進行第二次呼叫。

> [!WARNING]
>
> 這是谷歌原廠側可能出現的模型回顯或路由異常，**不代表你的請求違規，也不代表賬號被降權**。僅憑 `modelVersion` 無法斷定實際生成權重一定被切換，但一致性敏感的任務不應把這次結果當作目標模型的有效輸出。

## 怎麼確認遇到了這種情況

使用 Gemini 原生 `generateContent` 時，響應頂層同時包含 `modelVersion` 和 `responseId`：

```json theme={null}
{
  "candidates": [
    {
      "content": {
        "parts": [{ "text": "示例回答" }]
      },
      "finishReason": "STOP"
    }
  ],
  "modelVersion": "3.1-flash-lite-05-2026",
  "responseId": "example-response-id"
}
```

如果請求的是 `gemini-4-argon`，上面的回顯就不符合預期。即使正文正常、`finishReason` 為 `STOP`，也應在業務層單獨標記。

* **非流式**：檢查完整響應的 `modelVersion`。
* **流式**：檢查所有分塊，不能只看第一塊。公開復現中，同一個 `responseId` 的前置分塊與最終 `STOP` 分塊可能報告不同模型。
* **OpenAI 相容格式**：不要用響應裡的 `model` 代替這項檢查，它通常只是請求模型名。需要核對原廠回顯時，使用 Gemini 原生格式。

## 推薦處理流程

**1. 逐請求核對模型**

對固定模型 ID 使用嚴格比較：`response.model_version == requested_model`。回顯缺失時無法確認實際模型，也應標記為異常，而不是預設視為通過。

**2. 告警並保留原始結果**

記錄異常，但不要丟棄已經返回的正文和用量。它可以用於排查，也不應因一次回顯異常而立即產生第二次計費請求。

**3. 隔離任務，不中斷整批**

將當前任務標為 `needs_rerun`，繼續處理其餘任務。批處理報告至少彙總成功數、模型回顯異常數、其他失敗數和待重跑數。

**4. 人工確認後跑第二批**

從報告生成只包含異常任務 ID 的清單。第二批仍逐條核對模型，不覆蓋首輪報告，也不在程式碼裡做無限自動重試。

## Python 檢查示例

以下示例使用 `google-genai` SDK。它只發出一次請求，將判斷結果交給上層批處理程序，不包含自動重試：

```python theme={null}
import json
import os
import sys

from google import genai
from google.genai import types

requested_model = "gemini-4-argon"
task_id = "task-001"

with genai.Client(
    api_key=os.environ["APIYI_API_KEY"],
    http_options=types.HttpOptions(base_url="https://api.apiyi.com"),
) as client:
    response = client.models.generate_content(
        model=requested_model,
        contents="用一句話介紹你自己",
    )

actual_model = response.model_version
needs_rerun = actual_model != requested_model
record = {
    "task_id": task_id,
    "requested_model": requested_model,
    "model_version": actual_model,
    "response_id": response.response_id,
    "needs_rerun": needs_rerun,
    "answer": response.text,
}

if needs_rerun:
    print(
        f"WARNING {task_id}: requested={requested_model}, "
        f"returned={actual_model}, response_id={response.response_id}; "
        "not retrying automatically",
        file=sys.stderr,
    )

print(json.dumps(record, ensure_ascii=False))
```

流式呼叫的關鍵判斷是收集全部分塊的回顯，而不是隻儲存最後一個：

```python theme={null}
versions = set()
response_id = ""

for chunk in client.models.generate_content_stream(
    model=requested_model,
    contents="用一句話介紹你自己",
):
    if chunk.model_version:
        versions.add(chunk.model_version)
    if chunk.response_id:
        response_id = chunk.response_id

needs_rerun = versions != {requested_model}
```

只要集合為空、包含其他模型，或同時出現多個模型，`needs_rerun` 就為 `True`。正文仍需照常逐塊拼接，並另外檢查 `finishReason` 和用量欄位。

## 批次報告應該記錄什麼

| 欄位 | 用途 |
| - | - |
| `task_id` 或業務檔案相對路徑 | 定位哪一項任務需要重跑 |
| `requested_model` | 本次明確請求的模型 ID |
| `model_version` | 原生響應實際回顯的模型 |
| `response_id` | 結合時間排查具體請求 |
| `needs_rerun` / 異常原因 | 生成第二批清單，避免整批重跑 |
| 帶時區時間、耗時、tokens | 輔助判斷異常分佈和成本 |
| 原始正文與 `finishReason` | 保留證據，區分回顯異常與空響應、截斷 |

> [!NOTE]
>
> 日誌不要記錄 API Key。向客服或技術支援反饋時，提供請求模型、回顯模型、`responseId`、帶時區時間和可復現的脫敏請求即可，不要分享客戶內容或完整業務資料。

## 常見問題

> [accordion] 為什麼不建議發現不一致就立刻自動重試？
>
> 立即重試會放大請求量和費用，也可能在異常持續時形成重試風暴。先保留首輪證據、隔離異常任務，再按清單做有邊界的第二批，更容易定位和統計。若業務必須自動重試，也應設定最大次數、退避和熔斷，並把每次響應都記錄下來。

> [accordion] 回顯不一致是否說明回答一定來自 Flash-Lite？
>
> 不能僅憑欄位下定論。它可能是實際路由變化，也可能是版本或計量後設資料異常。無論根因是哪一種，對指定模型有硬性要求的任務都應將這次結果標為未通過模型一致性驗收。

> [accordion] 所有模型名都應該嚴格相等嗎？
>
> 對本文涉及的固定 Gemini 4 模型 ID，嚴格相等是最清楚的規則。如果主動使用 `latest` 等別名，回顯具體版本可能是正常行為，應改為校驗你明確接受的版本集合，而不是套用固定 ID 的規則。

> [accordion] 第二批仍然不一致怎麼辦？
>
> 停止繼續自動重跑，保留兩批報告。整理受影響的 `responseId`、請求與回顯模型、發生時間和脫敏復現請求，聯絡 APIYI 技術支援排查原廠側狀況。

## 相關文件

> [card] [Gemini 原生響應解析](https://docs.apiyi.com/zh-Hant/api-capabilities/gemini/response-handling.md)
>
> 非流式、流式、modelVersion、responseId 和用量欄位說明

> [card] [Gemini 原生呼叫指南](https://docs.apiyi.com/zh-Hant/api-capabilities/gemini/native.md)
>
> google-genai SDK、原生端點與思考引數配置

> [card] [Gemini 4 Carbon 模型切換記錄](https://docs.apiyi.com/zh-Hant/api-capabilities/gemini-4-carbon/overview.md)
>
> 已有公開復現現象、影響與使用建議

> [card] [Gemini 4 Argon 文本生成](https://docs.apiyi.com/zh-Hant/api-capabilities/gemini-4-argon/overview.md)
>
> Argon 模型 ID、雙端點與呼叫示例


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.