Spring AI 報 404 model_not_found：設定 key 寫錯

報 404 model_not_found、The model gpt-4o does not exist or you do not have access to it，先別急著懷疑模型掛了。九成是兩件事：模型名寫進了一個不生效的設定 key，被靜默忽略、回退到預設 gpt-4o；或者你的 key 根本沒權限訪問這個模型。

Issue & Env（案發現場與環境）

業務場景：Spring AI 接 OpenAI，調 ChatClient 生成文本，調用時拋 404。
環境：Spring AI 1.x（內置預設模型是 gpt-4o），Spring Boot 3.x，JDK 17+，OpenAI 官方 API。

StackTrace（堆疊日誌）

報錯原文是 OpenAI 返回的 404 JSON 響應：

{
    "error": {
        "message": "The model `gpt-4o` does not exist or you do not have access to it.",
        "type": "invalid_request_error",
        "param": null,
        "code": "model_not_found"
    }
}

Spring AI 拿到這個 404 後，會把它包成不可重試例外重新拋出。完整堆疊如下：

org.springframework.ai.retry.NonTransientAiException: 404 - {
    "error": {
        "message": "The model `gpt-4o` does not exist or you do not have access to it.",
        "type": "invalid_request_error",
        "param": null,
        "code": "model_not_found"
    }
}
    at org.springframework.ai.retry.RetryUtils.defaultTransientCallback(RetryUtils.java:67)
    at org.springframework.ai.openai.OpenAiChatModel.call(OpenAiChatModel.java:664)
    at org.springframework.ai.chat.client.DefaultChatClient$DefaultChatClientRequestSpec.call(DefaultChatClient.java:377)
    at com.example.service.ChatService.ask(ChatService.java:31)
    at com.example.controller.ChatController.chat(ChatController.java:45)
    at java.base/jdk.internal.reflect.DirectMethodHandleAccessor.invoke(DirectMethodHandleAccessor.java:103)

Reproduce（復現程式碼）

最常見的踩法：你想用 gpt-3.5-turbo，卻把模型名寫進了一個不生效的 key：

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      model: gpt-3.5-turbo   # 这个 key 不生效

然後照常調用：

String answer = chatClient.prompt()
    .user("hello")
    .call()
    .content();

報錯裡出現的卻是 gpt-4o，而不是你配的 gpt-3.5-turbo。

Root Cause（根因分析）

坑 1：模型設定 key 寫錯，被靜默忽略

Spring AI 裡模型名的正確路徑是 spring.ai.openai.chat.options.model，不是頂層的 spring.ai.openai.model。後者框架根本不讀，等於白寫。設定設了沒生效，就回退到內置預設模型，而 Spring AI 1.x 的預設值是 gpt-4o，於是請求打到了 gpt-4o 上。

如果你的賬戶還沒開通 gpt-4o，或者 key 沒有這個模型的權限，就直接 404。報錯裡冒出個你從沒配過的模型名，基本都是這條線：設定沒進對 key，回退預設值。這也和 issue #3857 一致——model_not_found 被歸類為不可重試錯誤（NonTransientAiException），框架知道這不是臨時故障，重試沒用。

坑 2：賬戶確實沒有該模型的訪問權限

文案是「does not exist or you do not have access to it」，兩個狀態被故意合併成一句。OpenAI 藉此掩蓋「模型不存在」和「你沒權限」，防止別人拿報錯去探測模型目錄。所以即便模型名寫對了，賬戶 tier 不夠、或項目裡沒給這個 key 開該模型權限，同樣是這句 404。

The Fix（解決方案）

先把模型名配進正確的 key：

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        options:
          model: gpt-4o-mini

chat.options.model 才是有效路徑。再排查權限：

用同一個 key 調 /v1/models，看它能列到哪些模型：

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

想用 gpt-4o 但列表裡沒有，多半是 billing tier 不夠。去 OpenAI 後臺提升 tier，或在項目裡給這個 key 加模型權限。
開發期用 gpt-4o-mini，它便宜且預設有權限，別一上來就 gpt-4o。