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

智能助手 PRO

需要 Scripting PRO

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

isAvailable 变量

描述

表示 Assistant API 当前是否可用。

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

requestStructuredData 方法

描述

requestStructuredData 允许用户发送自然语言提示，并根据定义好的 JSON Schema 接收结构化数据响应。 该方法现已支持两种形式：

  1. 仅文本输入版本
  2. 带图片输入版本 —— 可同时传入多张图片，让 AI 结合视觉内容进行结构化分析。

语法 1：文本输入版本

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

语法 2：带图片输入版本

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

参数说明

prompt (string)

自然语言提示，用于描述要解析的内容或任务。 例如：

“请从以下账单中提取金额、日期、类别和地点。”

images (string[])

要提供给模型的输入图片列表。每个元素应为 Base64 数据 URI 格式 的字符串，例如：

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...
  • 允许多张图片，但不建议一次传入过多图片，否则可能导致请求体过大或超时。
  • 可用于 OCR 账单识别、发票解析、图像场景分析等任务。

schema (JSONSchemaArray | JSONSchemaObject)

定义返回的 JSON 数据结构（参见下方 “JSON Schema 定义”）。

options（可选）

  • provider：

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

    值 说明
    "openai" 使用 OpenAI 模型（如 GPT-4、GPT-4-Turbo）
    "gemini" 使用 Google Gemini 模型
    "anthropic" 使用 Anthropic Claude 系列
    "deepseek" 使用 DeepSeek 模型
    "openrouter" 使用 OpenRouter 平台（可聚合多模型）
    { custom: string } 指定自定义的 API 提供商名称，例如自建代理服务

  • modelId：

    指定模型 ID（如 "gpt-4-turbo"、"gemini-1.5-pro"、"claude-3-opus" 等）。 如果未指定，则会自动使用应用中配置的该提供商的默认模型。

返回值

返回一个 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}

示例：解析图片中的发票信息

以下示例展示如何通过带图片输入的 requestStructuredData 方法，提取发票中的结构化数据：

1const prompt = "请从以下图片中提取发票金额、开票日期和商家名称"
2
3// const base64Data = UIImage.fromFile("/path/to/image.png").toJPEGBase64String(0.6)
4// const base64Image = `data:image/jpeg;base64,${base64Data}`
5
6const images = [
7  "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...", // 第一张发票图
8  "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."      // 第二张发票图
9]
10
11const schema: JSONSchemaObject = {
12  type: "object",
13  properties: {
14    total: { type: "number", description: "发票总金额", required: true },
15    date: { type: "string", description: "发票日期" },
16    merchant: { type: "string", description: "商家名称" }
17  },
18  description: "发票信息"
19}
20
21const result = await Assistant.requestStructuredData(
22  prompt,
23  images,
24  schema,
25  { provider: "gemini", modelId: "gemini-1.5-pro" }
26)
27
28console.log(result)

可能的输出：

1{
2  "total": 268.5,
3  "date": "2024-12-01",
4  "merchant": "深圳市优选超市"
5}

使用注意事项

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

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

  3. 明确选择 provider 和 modelId 若需使用特定模型（如 GPT-4、Gemini Pro），应通过 options 参数明确指定。

  4. 支持 OpenRouter 与自定义 Provider

    • "openrouter" 允许使用 OpenRouter 平台聚合的多种模型。
    • { custom: "your-provider" } 可用于自定义后端 API。

  5. 支持图片输入（多模态解析）

    • 仅部分模型（如 gpt-4-turbo、gemini-1.5-pro）支持图像输入。
    • 图片必须为 Base64 编码的 data:image/...;base64, 格式。
    • 不建议一次上传过多图片，以避免超时。

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

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}
大纲