> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# AI 功能

聊天、任务、模型策略与 bring-your-own-key。

## 尝试假人工智能，然后选择真正的提供商

对于您的第一个结果，请遵循 Web 教程的 /dashboard 任务：启动本地流程、对提示进行排队、运行它并查看结果。 AI_PROVIDER=fake 返回可重复的演示响应，无需将数据发送到外部模型或使用付费的 API 密钥。

对于真实生成，首先配置持久帐户，选择 AI 提供商并遵循下面的 AI 配置。将型号及其价格添加到数据库目录中，为每个别名选择允许的型号，并授予工作区所需的访问权限。诸如 fast 之类的别名是向用户显示的友好选择；它本身不是外部提供商的型号 ID。

后台AI task也需要配置的作业服务。如果未显示模型选择，请在重试之前检查目录和别名策略。如果访问被拒绝，请检查活动工作区的权利。将所有提供者 API 密钥保留在 Web 服务器的配置中，而不是浏览器、移动应用程序或桌面窗口中。

【尝试免凭证AI演示】(/docs/web/ship-in-5-minutes)

[配置真实AI生成](https://supastack.dev/zh/docs/modules/ai-configuration.md)

[添加允许的型号和价格](https://supastack.dev/zh/docs/web/setup-ai.md)

[配置后台任务执行](https://supastack.dev/zh/docs/modules/jobs.md)


## 跟随任务生命周期

生产任务 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 路径上。


## 下一篇

[后台任务](https://supastack.dev/zh/docs/web/jobs.md)