UI2项目实战：如何为应用添加意图(Intents)功能

什么是意图(Intents)？

在UI2项目中，意图(Intents)是一个核心概念，它允许开发者定义应用能够识别和处理的特定用户请求。简单来说，就是当用户输入某些内容时，你的应用能够理解用户的"意图"并执行相应的操作。

准备工作

在开始添加意图之前，确保你已经完成了UI2的基本配置。你需要：

1. 安装必要的依赖包
2. 配置好AI模型（如示例中的Cerebras模型）
3. 准备好Zod库用于参数验证

创建第一个意图：数字相加

让我们从一个简单的例子开始 - 创建一个能够将两个数字相加的意图。

import { createUI2 } from "ui2-sdk";
import { z } from "zod";
import { createCerebras } from "@ai-sdk/cerebras";

const cerebras = createCerebras({
    apiKey: "API_KEY",
});

let { identifyIntent } = createUI2({
    model: cerebras("llama-3.3-70b"),
}).addIntent("sum", {
    parameters: z.object({
        a: z.number(),
        b: z.number(),
    }),
    description: "Add two numbers together",
    onIntent: (intentCall) => {
        console.log(
            `${intentCall.parameters.a} + ${intentCall.parameters.b} = ${
                intentCall.parameters.a + intentCall.parameters.b
            }`
        );
    },
});

代码解析

1. 模型配置：我们首先创建了一个Cerebras模型的实例，并提供了API密钥。

2. UI2初始化：使用createUI2函数初始化UI2，并指定要使用的AI模型。

3. 添加意图：通过.addIntent()方法添加一个名为"sum"的意图。

意图的四个关键部分

1. 名称(Name)："sum"是意图的唯一标识符，应该简洁明了，遵循变量命名规范。

2. 描述(Description)："Add two numbers together"帮助AI理解这个意图的用途，在识别用户请求时起到关键作用。

3. 参数(Parameters)：使用Zod库定义了一个包含两个数字(a和b)的参数对象。Zod提供了强大的类型验证功能。

4. 处理函数(onIntent)：当意图被识别时执行的回调函数，这里我们简单地将两个数字相加并打印结果。

参数验证的重要性

UI2利用Zod的Structured Output功能，确保AI的输出严格符合你定义的参数模式。这意味着：

• 类型安全：参数会被自动验证为正确的类型
• 自动补全：在IDE中可以获得参数的类型提示
• 错误处理：无效的输入会被自动拦截

添加第二个意图：数字平方

UI2的一个强大特性是可以轻松地添加多个意图。让我们添加一个计算数字平方的意图：

let { identifyIntent } = createUI2({
    model: cerebras("llama-3.3-70b"),
})
    .addIntent("sum", {
        // 之前的sum意图配置
    })
    .addIntent("square", {
        parameters: z.object({
            a: z.number(),
        }),
        description: "Squares a number",
        onIntent: (intentCall) => {
            console.log(
                `${intentCall.parameters.a}^2 = ${
                    intentCall.parameters.a * intentCall.parameters.a
                }`
            );
        },
    });

意图链式调用

通过链式调用.addIntent()方法，我们可以不断地为应用添加新的功能。每个意图都是独立的，但共享同一个AI模型和配置。

意图调用的详细信息

当意图被识别时，onIntent回调会收到一个intentCall对象，包含：

• name：被调用的意图名称
• id：唯一标识符，可用于跟踪或防止重复调用
• parameters：经过验证的参数对象，完全符合你定义的Zod模式

最佳实践

1. 命名规范：使用简洁但具有描述性的名称，如"calculateTotal"比"calc"更好。

2. 参数设计：保持参数结构简单明了，复杂的嵌套结构可能会降低AI的识别准确率。

3. 描述清晰：为意图和参数提供详细的描述，这能显著提高AI的理解能力。

4. 错误处理：考虑在onIntent中添加错误处理逻辑，以应对可能的运行时错误。

总结

通过UI2的意图系统，开发者可以轻松地为应用添加自然语言处理能力。本文通过两个简单的数学运算示例，展示了如何：

1. 初始化UI2并配置AI模型
2. 定义意图的名称、描述和参数
3. 实现意图被识别时的处理逻辑
4. 扩展应用功能，添加多个意图

这种模式不仅适用于简单的数学运算，可以扩展到各种复杂的业务场景，如数据查询、系统控制、内容生成等。UI2的意图系统提供了一种结构化的方式来构建智能的、可理解自然语言命令的应用。