Cetai(鲸语)
在普通 Rust 代码中用带类型的
prompt!表达式执行自然语言任务,并安全地取得结构化结果。
Cetai 是一个 AI 调用实验的 Rust MVP:普通逻辑继续写 Rust,难以用确定性代码表达的理解、提取与生成任务写进 prompt!,由 DeepSeek 在运行时完成。既可以用 #[ai] 声明一个完整的 AI 函数,也可以把 prompt! 作为表达式嵌入普通 Rust 代码。
[!IMPORTANT] Cetai 处于 MVP 阶段(0.1.x),API 以本文件与 PLAN.md 描述为准,后续版本可能调整。
安装
API 文档见 docs.rs/cetai。
用法
use ;
use JsonSchema;
use ;
async
async
调用方式保持普通 Rust 异步函数的形态,并显式处理模型和网络错误:
async
可运行的完整示例见 cetai/examples/summarize.rs(cargo run -p cetai --example summarize)。
#[ai] 形式适合整个函数只做一次模型调用的情况;它等价于在函数体内执行 prompt!(...).await。表达式形式适合取得结果后继续执行普通 Rust 逻辑。两种形式共用同一个 prompt! 实现、类型约束、错误模型和运行时。
{article} 是经过编译期校验的局部绑定引用,不是字符串插值。prompt! 只把实际引用的值按共享引用序列化,未引用的参数、self、解构或通配模式不会影响它。提示词随编译产物固定,参数值会单独序列化为 JSON 后发送给模型。
配置 DeepSeek API key
先按 DeepSeek 官方快速开始 创建 API key。Cetai 默认只从当前进程的 DEEPSEEK_API_KEY 环境变量读取密钥,也允许应用通过 AiConfig 显式传入从密钥管理服务取得的值。API key 不进入宏参数、源代码、生成的提示词、日志或错误信息。Cetai 库本身不会自动读取 .env 文件,避免库代码在宿主应用不知情时修改进程配置。
本地开发可以由应用在第一次 Cetai 调用前使用 dotenvy 等工具加载一个不提交到 Git 的 .env:
# .env
DEEPSEEK_API_KEY=在本地填写真实密钥
宿主应用负责在第一次 Cetai 调用前加载它;例如应用依赖 dotenvy 时:
let _ = dotenv;
let config = from_env?;
init?;
仓库应忽略本地密钥文件,只提交不含真实值的模板:
.env
.env.*
!.env.example
# .env.example
DEEPSEEK_API_KEY=
CI 和生产环境应通过平台的 Secret/密钥管理功能注入 DEEPSEEK_API_KEY,不得把真实密钥写入仓库、构建参数、命令行参数或容器镜像。未显式调用 cetai::init 时,Cetai 会在第一次调用时直接读取已经存在的进程环境变量。
在 Bevy 中使用
cetai 的 HTTP 传输层由公开的 Transport trait 抽象(TransportRequest / TransportResponse / TransportError,含 send 与 sleep),默认 feature reqwest-transport 保持 reqwest + tokio 行为不变。cetai-bevy 是 bevy 插件,基于 ehttp 与 wasm-timer 实现该 trait(BevyTransport),不依赖 tokio,原生与 wasm32 目标均可运行。
[!WARNING] 与应用中直接依赖
cetai时必须关闭其默认 feature:= { = "0.1", = false } = "0.1"否则 feature 统一会激活 reqwest+tokio 传输层,而 Bevy 应用没有 tokio runtime,
AiConfig会拿到错误的默认 transport。关闭默认 feature 后由CetaiPlugin装入BevyTransport。
use *;
use prompt;
use ;
cetai-bevy 支持 wasm32-unknown-unknown 目标。需要注意:wasm 构建中 API key 会随前端代码一起分发,任何能打开页面的人都能取得它。公开部署的 Web 版本应通过自有后端代理转发模型请求(可配合 DEEPSEEK_BASE_URL 指向代理),不要在前端代码中直接放置官方 API key。
cetai-bevy 与 cetai、bevy 的版本对应关系:
| cetai-bevy | cetai | bevy |
|---|---|---|
| 0.1 | 0.1 | 0.19 |
完整可运行的游戏示例见 examples/bevy-demo(独立 crate,不进入 workspace)。
设计重点
#[ai]是完整 AI 函数的语法糖,函数体只写一个prompt!,调用者通过函数的.await取得结果。prompt!返回Future<Output = cetai::Result<T>>,通过.await?显式处理异步和失败。prompt!接受普通或原始字符串字面量,支持多行文本以及对参数和局部变量的具名引用。- 思考强度使用有类型的
Thinking::OFF / HIGH / MAX,不在 Rust API 中传递字符串档位。 http_retries与repair_retries可以在prompt!或#[ai]上用0..=10的整数字面量逐调用覆盖;初始请求和每次修复请求分别拥有自己的 HTTP 重试预算。max_tokens默认按思考档位自动取模型最大输出的 15%/30%/60%(OFF/HIGH/MAX),可用环境变量、AiConfig或逐调用宏参数(1..=384000)覆盖。- 宏只借用并序列化提示词引用的绑定,调用完成后原值仍可继续使用。
- 返回类型生成 JSON Schema;模型结果经过本地校验和反序列化后才返回。
- 网络、配置和模型输出错误通过
AiError暴露,不以 panic 作为正常失败方式。 - MVP 直接对接 DeepSeek 的 HTTP API,只做非流式结构化调用。
- HTTP 传输层可替换:默认 feature
reqwest-transport保持 reqwest + tokio 行为不变,经公开的Transporttrait 可换成其它实现(Bevy 与 wasm32 支持见cetai-bevy)。 - 上下文缓存只是一项可观测优化;命中、用量和重试统计通过脱敏的结构化 tracing 事件暴露,不构成正确性或成本承诺。
重要限制
prompt!调用具有网络延迟、费用、非确定性和失败可能,不适合热路径。- JSON Schema 只能约束结果结构,不能保证内容在语义上正确。
- 输入会发送给第三方模型;敏感数据、隐私要求和提示词注入需要由应用评估。
{self}会序列化整个接收者;只需要个别字段时,应先绑定字段引用再放入提示词。- 普通函数可以包含零个、一个或多个
prompt!;每次调用都是独立的网络请求并产生独立费用。 - 第一阶段是 Rust crate,不是独立编程语言。
名称与文件后缀
项目中文名为“鲸语”,英文名为 Cetai,由 cetacean 与 AI 组合而来。计划中的 crate 和 CLI 均使用 cetai。
未来若独立语言得到验证,其源文件后缀使用 .cai,例如 main.cai。当前 Rust MVP 的源文件仍然是 .rs。
设计计划
完整的产品边界、公开语法、运行时语义、错误模型和验收标准见 PLAN.md。
开发
DEEPSEEK_API_KEY=...