For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /zh-tw/docs/tanstack/ai.md (or send Accept: text/markdown).

AI 功能

聊天、任務、模型策略與 bring-your-own-key。

詢問本指南

嘗試假人工智慧，然後選擇真正的提供商

對於您的第一個結果，請遵循 Web 教程的 /dashboard 任務：啟動本地流程、對提示進行排隊、執行它並檢視結果。 AI_PROVIDER=fake 返回可重複的演示響應，無需將資料傳送到外部模型或使用付費的 API 金鑰。

對於真實生成，首先配置持久帳戶，選擇 AI 提供商並遵循下面的 AI 配置。將型號及其價格新增到資料庫目錄中，為每個別名選擇允許的型號，並授予工作區所需的訪問許可權。諸如 fast 之類的別名是向用戶顯示的友好選擇；它本身不是外部提供商的型號 ID。

後臺AI task也需要配置的作業服務。如果未顯示模型選擇，請在重試之前檢查目錄和別名策略。如果訪問被拒絕，請檢查活動工作區的權利。將所有提供者 API 金鑰保留在 Web 伺服器的配置中，而不是瀏覽器、移動應用程式或桌面視窗中。

跟隨任務生命週期

生產任務 API 在持久化任務並派發 Trigger.dev 的 ai.generate 工作流之前，先驗證已認證的工作區與許可權。路由器應用能力要求與已配置的模型策略。

POST /api/ai/tasks
  → authenticated workspace + entitlement
  → durable task record
  → Trigger.dev ai.generate
  → model routing + generation
  → usage record + result
  → transactional completion delivery

配置別名與預算

使用者選擇已啟用的別名：cheap、fast 或 smart。服務端控制底層模型 ID、供應商憑證、工作區策略與預算執行。加密的自帶金鑰支援必須保持同樣的服務端邊界。

讓工作流語義保持顯式

JobRunner 只承諾 enqueue、status 與 cancel。Trigger.dev 的工作流語義是顯式的，包括持久執行行為。不要從通用契約推斷重試或排程保證。

生產提交路徑使用冪等與已儲存任務恢復來處理模糊派發。生成完成與完成郵件投遞是兩件事。

安裝與配置

AI_PROVIDER=fake 讓開發保持確定性。生產提供商在伺服器端配置(OpenAI、Anthropic 或 OpenAI 相容端點),金鑰永遠不會進入客戶端包。AI_MODEL_POLICY 將面向使用者的別名(cheap、fast、smart)對映到目錄中的模型 id;空別名會從介面中移除該選項。

模型目錄(ai-model-catalog)攜帶能力與不可變的價格後設資料,因此價格變動後使用記錄仍然可解釋。

POST /api/ai/tasks          → durable task + Trigger.dev dispatch
GET  /api/ai/tasks/{taskId}  → status + result
/chat                        → streaming assistant surface

實現流程

聊天介面按工作區成員維護會話執行緒,並通過 chat-stream-runtime 流式傳輸 token。較長的生成作為任務執行:在 API 邊界授權、由 ai.generate 工作流執行,並可通過冪等提交儲存恢復。

bring-your-own-key 模式將提供商金鑰儲存為 AES-GCM 信封(CREDENTIAL_ENCRYPTION_KEY、byok-key-vault.ts);解密只發生在伺服器執行路徑內。每次請求記錄用量與估算成本,用於工作區預算。

驗證與排障

驗證已停用的別名從介面中消失、entitlement 與預算拒絕發生在分發之前、重試的提交複用其任務,以及已儲存的 BYOK 金鑰永遠不會返回客戶端。將真實模型驗收保留在檔案化的提供商 smoke 路徑上。