cetai 0.1.1

Typed prompt! expressions and #[ai] functions for natural-language tasks over DeepSeek.
Documentation

Cetai(鲸语)

crates.io docs.rs ci

在普通 Rust 代码中用带类型的 prompt! 表达式执行自然语言任务,并安全地取得结构化结果。

Cetai 是一个 AI 调用实验的 Rust MVP:普通逻辑继续写 Rust,难以用确定性代码表达的理解、提取与生成任务写进 prompt!,由 DeepSeek 在运行时完成。既可以用 #[ai] 声明一个完整的 AI 函数,也可以把 prompt! 作为表达式嵌入普通 Rust 代码。

[!IMPORTANT] Cetai 处于 MVP 阶段(0.1.x),API 以本文件与 PLAN.md 描述为准,后续版本可能调整。

安装

cargo add cetai

API 文档见 docs.rs/cetai。

用法

use cetai::{ai, prompt};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize, JsonSchema, Debug)]
struct Summary {
    text: String,
    points: Vec<String>,
}

#[ai]
async fn summarize(article: String) -> cetai::Result<Summary> {
    prompt!(r#"
        请总结 {article}:
        1. 用一句话概括
        2. 提取 3 个关键点
    "#)
}

async fn summarize_and_print(article: String) -> cetai::Result<()> {
    let summary: Summary = prompt!(r#"
        请总结 {article}:
        1. 用一句话概括
        2. 提取 3 个关键点
    "#, http_retries = 2, repair_retries = 1)
    .await?;

    // prompt! 只借用被引用的值,调用结束后仍可继续使用 article。
    println!("原文长度:{}", article.len());
    println!("{}", summary.text);
    Ok(())
}

调用方式保持普通 Rust 异步函数的形态,并显式处理模型和网络错误:

#[tokio::main]
async fn main() -> cetai::Result<()> {
    summarize_and_print("……一篇长文……".into()).await?;
    Ok(())
}

可运行的完整示例见 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 _ = dotenvy::dotenv();
let config = cetai::AiConfig::from_env()?;
cetai::init(config)?;

仓库应忽略本地密钥文件,只提交不含真实值的模板:

.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 目标均可运行。

cargo add cetai-bevy

[!WARNING] 与应用中直接依赖 cetai 时必须关闭其默认 feature:

cetai = { version = "0.1", default-features = false }
cetai-bevy = "0.1"

否则 feature 统一会激活 reqwest+tokio 传输层,而 Bevy 应用没有 tokio runtime,AiConfig 会拿到错误的默认 transport。关闭默认 feature 后由 CetaiPlugin 装入 BevyTransport。

use bevy::prelude::*;
use cetai::prompt;
use cetai_bevy::{Cetai, CetaiPlugin};

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        // 装配 Cetai 插件;API key 与配置规则和 cetai 保持一致
        .add_plugins(CetaiPlugin::default())
        .add_systems(Update, handle_input)
        .run();
}

fn handle_input(ai: Cetai, keys: Res<ButtonInput<KeyCode>>) {
    if !keys.just_pressed(KeyCode::Enter) {
        return;
    }
    let article = "……一篇长文……";
    // ask 立即返回;回调经完成队列在主线程执行,可以照常访问 World
    ai.ask(
        prompt!("请用一句话总结 {article}"),
        |world, result: cetai::Result<String>| match result {
            Ok(text) => {
                // 例如经 world 把结果写回资源或组件
                info!("总结:{text}");
            }
            Err(error) => warn!("总结失败:{error}"),
        },
    );
}

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 行为不变,经公开的 Transport trait 可换成其它实现(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。

开发

cargo test                                 # 单元、编译期与 mock 集成测试(默认成员)
cargo check -p cetai-bevy --all-targets    # Bevy 插件
DEEPSEEK_API_KEY=... cargo test -p cetai --test real_api -- --ignored   # 真实 API 门控测试