AI Task Starter

受众：开发者 摘要：轻量 AI 任务模型 + handler 注册 + 同步执行 + 失败结果转换。核心不绑模型 SDK / 数据库；需要异步、定时和多步骤时，用可选 Queue / Scheduler / Pipeline 助手组合。

何时使用

场景	建议
统一描述「一个 AI 任务怎么找到处理器并执行」	AiTask.run(...)
同步调用业务 handler（短任务、调试、首版）	AiTask Facade
异步执行	同时引入 Queue starter，用 AiTaskQueue.dispatch(...) 或通用 job ai-task.run
定时 / 周期触发	同时引入 Scheduler starter，继承 AiTaskSchedulerTask
单次任务内部多步骤	同时引入 Pipeline starter，用 AiTaskPipelineContext 承载上下文
上下文检索	先调 Knowledge.ask(...)，结果传入 metadata
对外开放 AI 能力	走 Open Platform 边界，不直接暴露

AI Task 不做数据库任务状态、失败重试、模型 Provider 和后台运维页。这些由 Queue / Scheduler / Pipeline、Runtime 或具体业务模块负责。

快速开始

Java 包名统一为 com.springopen.starter.ai.task，与 AI 模型 的 com.springopen.starter.ai.model 同属 ai 能力域。

<dependency>
    <groupId>com.springopen</groupId>
    <artifactId>spring-open-starter-ai-task</artifactId>
</dependency>

实现 handler：

@Component
public class SummaryAiTaskHandler implements AiTaskHandler {

    @Override
    public String getType() {
        return "summary";
    }

    @Override
    public AiTaskOutput handle(AiTaskContext context) {
        String text = (String) context.getInput().get("text");
        return AiTaskOutput.builder()
                .data(Map.of("summary", text.substring(0, Math.min(text.length(), 80))))
                .message("ok")
                .build();
    }
}

执行：

AiTaskResult result = AiTask.run("summary", Map.of("text", "需要总结的内容"));

Facade API

// 完整请求
AiTaskResult result = AiTask.run(AiTaskRequest.builder()
        .type("summary")
        .input(Map.of("text", "需要总结的内容"))
        .metadata(Map.of("source", "manual"))
        .build());

// 快捷
AiTaskResult result = AiTask.run("summary", Map.of("text", "..."));

AiTaskResult 字段：

字段	说明
taskId	任务 ID
type	任务类型
status	success / failed
output	业务输出（Map）
message	文本说明
exception	失败时的异常类型
elapsedMillis	耗时

源码机制骨架

AI Task starter 采用 Facade -> Manager -> Registry -> Handler 的轻量分层。核心只处理同步任务执行 contract；Queue、Scheduler、Pipeline 组合助手是 optional 层，不改变核心边界。

层	类	职责
Facade	AiTask	业务侧静态入口：AiTask.run(type, input) / AiTask.run(request)
Manager	AiTaskManager / DefaultAiTaskManager	解析默认 type、生成 taskId、构造 AiTaskContext、查找 handler、执行并返回 AiTaskResult
Registry	AiTaskHandlerRegistry / DefaultAiTaskHandlerRegistry	收集 Spring 中的 AiTaskHandler，按 type 归一化后注册；同 type 第一阶段只保留第一个
Handler	AiTaskHandler	单个任务类型的实际业务逻辑，可在内部组合 Knowledge、AI Model、Pipeline 或业务 Service
Request	AiTaskRequest	调用侧输入，包含 type、input 和 metadata
Context	AiTaskContext	Manager 构造的执行上下文，包含 taskId、解析后的 type、input 和 metadata
Output	AiTaskOutput	handler 返回的业务输出和说明
Result	AiTaskResult / AiTaskStatus	本次同步执行结果、输出、异常和耗时
Auto Configuration	AiTaskAutoConfiguration / AiTaskManagerProvider	注册默认 Manager / Registry，并把 Manager 绑定到静态 Facade
Queue Helper	AiTaskQueue / AiTaskQueueJob / AiTaskQueueJobHandler	可选异步投递和通用 Queue Job Handler，底层仍走 Queue
Scheduler Helper	AiTaskSchedulerTask	可选定时任务抽象，调度事实写入 metadata，底层仍走 Scheduler
Pipeline Helper	AiTaskPipelineContext	可选 Pipeline 上下文适配，底层仍走 Pipeline

关键机制顺序：

1. 调用方通过 AiTask.run(...) 提交请求。
2. DefaultAiTaskManager 用请求 type 或 default-type 得到任务类型。
3. DefaultAiTaskHandlerRegistry 按归一化 type 查找 handler。
4. Manager 生成 taskId，构造 AiTaskContext。
5. handler 同步执行并返回 AiTaskOutput。
6. Manager 转换为 AiTaskResult，写入状态、输出、消息和耗时。
7. handler 异常默认转为 FAILED；关闭 catch-handler-exception 后异常直接抛出。

扩展边界

AI Task 没有 Provider 切换，也不拥有自己的任务状态机。扩展点保持简单：

• 新任务类型：实现新的 AiTaskHandler Bean。
• 异步执行：使用 AiTaskQueue.dispatch(...) 或通用 job ai-task.run，失败重试和 worker 由 Queue 负责。
• 周期执行：继承 AiTaskSchedulerTask，调度实例、执行日志和暂停恢复由 Scheduler 负责。
• 多步骤任务：使用 AiTaskPipelineContext 组合 Pipeline。
• 上下文检索：在 handler 或 Pipeline 步骤中调用 Knowledge。
• 模型调用：在 handler 内调用 AI Model starter 或业务 Service。

不要把数据库任务状态、失败重试、后台运维页、用户 API Key、套餐和扣费塞进 AI Task starter；这些属于 Runtime、Queue、Scheduler、Open Platform 或具体业务模块。

配置项

spring:
  open:
    ai-task:
      enabled: true
      default-type: default
      catch-handler-exception: true

配置	默认值	说明
enabled	true	启用开关
default-type	default	请求未传 type 时使用
catch-handler-exception	true	handler 异常转失败结果

Provider

AI Task 本身不提供 Provider 切换。扩展通过：

• 实现 AiTaskHandler Bean 注册新 type
• 多 handler 同 type 时第一阶段只保留第一个；复杂编排用 Pipeline

模型 Provider 由业务 handler 内部决定（OpenAI / Anthropic / 本地模型 / 自研接口），第一阶段框架不绑定 SDK。

与 Queue 协作

AI Task 核心不强制依赖 Queue；spring-open-starter-ai-task 对 Queue 是 optional 依赖。应用同时引入 Queue starter 后，可以直接使用通用 job：

AiTaskQueue.prepare(AiTaskRequest.builder()
                .type("summary")
                .input(Map.of("text", "..."))
                .metadata(Map.of("source", "manual"))
                .build())
        .onQueue("ai")
        .maxAttempts(3)
        .dispatch();

AiTaskQueueJobHandler 会自动注册为 QueueJobHandler，job 名称固定为 ai-task.run。失败重试、失败任务查询、worker 并发、多实例消费由 Queue 负责。

与 Scheduler 协作

@Component
public class DailyKnowledgeSummaryTask extends AiTaskSchedulerTask {

    public DailyKnowledgeSummaryTask(AiTaskManager aiTaskManager) {
        super(aiTaskManager);
    }

    @Override public String name() { return "ai-task.knowledge-summary"; }

    @Override protected AiTaskRequest request(SchedulerTaskContext context) {
        return AiTaskRequest.builder()
                .type("knowledge.summary")
                .metadata(Map.of(
                        "source", "scheduler"))
                .build();
    }
}

Scheduler.cron("ai-task.knowledge-summary", "daily", "0 0 2 * * *");

Scheduler 负责触发时机、任务实例、执行日志和失败运维。

与 Pipeline 协作

handler 内部有多稳定步骤时嵌入 Pipeline：

@Component
public class RagAnswerAiTaskHandler implements AiTaskHandler {
    @Override public String getType() { return "rag.answer"; }
    @Override public AiTaskOutput handle(AiTaskContext context) {
        AiTaskPipelineContext pc = AiTaskPipelineContext.from(context)
                .put("question", context.getInput().get("question"));

        Pipeline.execute("ai-task.rag-answer", pc);

        return AiTaskOutput.builder()
                .data(Map.of("answer", pc.get("answer")))
                .message("ok")
                .build();
    }
}

典型步骤：校验输入 → Knowledge 检索 → 组装 prompt → 调模型 → 写结果 / 发通知。

Pipeline 负责单次任务内部有序步骤和中断，不负责异步 / 重试 / 定时 / 持久化。

与 Knowledge 协作

KnowledgeAskResult knowledge = Knowledge.ask(KnowledgeAskRequest.builder()
        .question((String) context.getInput().get("question"))
        .topK(6)
        .returnContext(true)
        .build());

把 contexts 和 citations 放入 metadata 或 Pipeline context，由后续步骤决定如何生成回答。

与 Open Platform 协作

对外开放 AI 能力时：

Open Platform API
  → 权限 / 签名 / 限流
  → AI Task Service
  → Queue / Scheduler / Pipeline / Knowledge
  → 业务结果
  → 调用日志和统计

Controller 不直接调模型 SDK。Open Platform 负责 AK/SK、scope、限流、调用日志、配额、套餐和计费。

当前边界

已具备	暂不包含
AiTask Facade / AiTaskManager / AiTaskHandler	数据库任务状态
Spring 自动注册 handler	自有任务状态机
同步执行 + 失败结果转换	失败重试
可选 Queue / Scheduler / Pipeline 组合助手	模型 Provider / 后台页

开发约定

• handler 用 @Component 注册，getType() 全局唯一
• handler 不自己管理事务、重试和异步
• 模型调用、网络请求放 handler 内部，不写进 Controller
• 异常默认转失败结果，不让 handler 异常直接抛给调用方
• 输入和 metadata 都用 Map<String, Object>，不绑业务专属类型
• 长耗时任务走 Queue 异步，不让同步 AiTask.run 阻塞 HTTP 请求

验证命令

./mvnw -pl spring-open-starters/spring-open-starter-ai-task -am test -DskipITs
./mvnw -pl spring-open-application -am test -DskipITs -DskipFrontend

相关

• 队列：queue.md
• 任务调度：scheduler.md
• 管道：pipeline.md
• 知识库：knowledge.md
• 开放平台：open-platform.md
• Provider 扩展模型：provider.md