Scripting
开始
文档
更新日志
隐私
开始
文档
更新日志
隐私
简体中文

智能助手

Assistant 模块提供了一套强大的 API，允许用户通过智能助手请求结构化的 JSON 数据。该功能可用于自动化任务，例如提取账单信息、分类支出、解析文本等。

isAvailable 变量

描述

表示 Assistant API 当前是否可用。

  • 此状态取决于所选的 AI 提供商及其 API 密钥是否已配置。
  • 如果未提供有效的 API Key，Assistant API 将无法使用。

requestStructuredData 方法

描述

requestStructuredData 允许用户发送自然语言提示，并根据定义好的 JSON Schema 接收结构化数据响应。

语法

1function requestStructuredData<R>(
2  prompt: string,
3  schema: JSONSchemaArray | JSONSchemaObject,
4  options?: {
5    provider: "openai" | "gemini" | "anthropic" | "deepseek" | "pollinations" | { custom: string }
6    modelId?: string
7  }
8): Promise<R>

参数说明

  • prompt (string)： 自然语言提示，用于描述要解析的内容或任务。

  • schema (JSONSchemaArray | JSONSchemaObject)： 定义返回 JSON 数据结构的模式。

  • options（可选）：

    • provider： 指定要使用的 AI 提供商。支持以下值：

      • "openai"：使用 OpenAI 模型（如 GPT-4）
      • "gemini"：使用 Google Gemini
      • "anthropic"：使用 Claude 系列
      • "deepseek"：使用 DeepSeek 模型
      • "pollinations"：使用 Pollinations 模型
      • { custom: string }：指定自定义的 API 提供商名称

    • modelId： 指定提供商对应的模型 ID（如 "gpt-4-turbo"、"gemini-1.5-pro" 等）。如果未指定，将使用 app 中当前默认模型。

返回值

返回一个 Promise，解析为符合 schema 所定义结构的 JSON 数据，类型为 R。

JSON Schema 定义

schema 参数定义了返回数据的结构类型：

JSONSchemaType

1type JSONSchemaType = JSONSchemaPrimitive | JSONSchemaArray | JSONSchemaObject

原始类型（Primitive）

1type JSONSchemaPrimitive = {
2  type: "string" | "number" | "boolean"
3  required?: boolean
4  description: string
5}

数组类型（Array）

1type JSONSchemaArray = {
2  type: "array"
3  items: JSONSchemaType
4  required?: boolean
5  description: string
6}

对象类型（Object）

1type JSONSchemaObject = {
2  type: "object"
3  properties: Record<string, JSONSchemaType>
4  required?: boolean
5  description: string
6}

示例：提取账单信息

假设你有一段账单文本，想要提取金额、日期、类别和地点：

1const someBillDetails = `
2- 金额：$15.00
3- 日期：2024-03-11 14:30
4- 地点：城市中心停车场
5- 类别：停车
6`
7
8const prompt = `请解析以下账单信息并输出结构化数据：${someBillDetails}`
9
10const schema: JSONSchemaObject = {
11  type: "object",
12  properties: {
13    totalAmount: {
14      type: "number",
15      required: true,
16      description: "账单总金额"
17    },
18    category: {
19      type: "string",
20      required: true,
21      description: "账单类别"
22    },
23    date: {
24      type: "string",
25      required: false,
26      description: "账单日期"
27    },
28    location: {
29      type: "string",
30      required: false,
31      description: "账单地点"
32    }
33  }
34}
35
36const data = await Assistant.requestStructuredData(
37  prompt,
38  schema,
39  {
40    provider: "openai",
41    modelId: "gpt-4-turbo"
42  }
43)
44
45console.log(data)

可能的输出结果：

1{
2  "totalAmount": 15.00,
3  "category": "停车",
4  "date": "2024-03-11 14:30",
5  "location": "城市中心停车场"
6}

使用注意事项

  1. 确保 schema 定义合理 返回的数据结构必须与定义的 schema 匹配，否则可能解析失败。

  2. 合理设置 required 字段 对于必须存在的字段，务必设置 required: true，可选字段可省略。

  3. 明确选择 provider 和 modelId 如需使用特定模型（如 GPT-4），应通过 options 参数指定提供商和模型 ID。

  4. 建议加入错误处理逻辑

1try {
2  const result = await Assistant.requestStructuredData(prompt, schema, {
3    provider: { custom: "my-ai-backend" },
4    modelId: "my-custom-model"
5  })
6  console.log("解析结果：", result)
7} catch (err) {
8  console.error("解析失败：", err)
9}
大纲