@clickzetta/cz-cli-darwin-x64 0.3.1

package/bin/skills/lakehouse-doc/references/702bc8f656.md

@@ -0,0 +1,387 @@
+## 如何将飞书上的表格导入到lakehouse中
+
+## 1. **前期准备说明**
+
+飞书应用的创建：获取应用凭证信息
+
+云器Lakehouse的账号信息：登录云器web页面创建脚本任务导入数据
+
+目标表格类型确认：此部分很重要！需要基于目标表格的类型明确需要开通的系列权限。
+
+## 2. **飞书应用创建与配置**
+
+### 创建飞书应用
+
+#### 步骤1：登录飞书开放平台
+
+访问：<https://open.feishu.cn/>
+
+使用飞书账号登录
+
+点击右上角"进入开发者后台"
+
+![](.topwrite/assets/702bc8f656/84b36fb92c71d784ac5232a6d14363a3ce7b1ca9.png =200)
+
+#### 步骤2：创建应用
+
+点击"创建应用"
+
+选择"企业自建应用"
+
+填写应用信息：
+
+**应用名称**：云器数据同步应用
+
+**应用描述**：将飞书表格数据同步到云器lakehouse中
+
+**应用图标**：上传应用图标（可选）
+
+#### 步骤3：获取应用凭证
+
+创建完成后，在左侧菜单"凭证与基础信息"页面记录：
+
+**App ID**：cli\_xxxxxxxxxx
+
+**App Secret**：xxxxxxxxxxxxxxxx
+
+### 配置应用权限
+
+在配置权限前，请先确认需要导入的文件类型，并基于飞书文档的权限要求开通相应的权限。本文以电子表格（sheets）为例进行操作说明。具体类型可参考[飞书API文档](https://open.feishu.cn/document/server-docs/docs/docs-overview)
+
+#### 步骤1：申请权限范围
+
+进入"权限管理"页面
+
+搜索并添加以下权限：
+
+**表格相关权限**：
+
+sheets:spreadsheet - 查看、评论、编辑和管理工作表
+
+sheets:spreadsheet:readonly - 查看工作表
+
+drive:drive - 查看云文档文件夹
+
+**具体操作**：
+
+> 权限范围 → 搜索"sheets" → 勾选以下权限：
+> &#x20;1、查看、评论、编辑和管理工作表
+> &#x20;2、查看和编辑电子表格
+> &#x20;3、查看云文档文件夹
+
+#### 步骤2：申请权限审批
+
+点击"创建版本"
+
+填写版本说明：数据同步功能上线
+
+提交审核（如果是企业内部应用，通常自动通过）
+
+#### 步骤3：应用发布
+
+审核通过后，点击"申请线上发布"
+
+选择发布范围：
+
+**全员可见**：推荐选择
+
+**指定部门**：根据需要选择
+
+### 获取表格访问权限
+
+注意：若是企业用户，除了在应用开发中配置权限，还需要在文档中开通应用访问权限。
+
+1. 打开目标飞书表格
+2. 点击页面右上角...-->选择更多-->添加文档应用
+
+   ![](.topwrite/assets/702bc8f656/d2431b8bc2172f0528f9b4015bafc0eef754e3ff.png =200)
+3. 配置文档应用权限
+   搜索应用名称：云器数据同步应用
+   设置权限：**可编辑**（确保能读取数据）
+
+### 记录关键信息
+
+**应用凭证**：是飞书开放平台应用的身份标识和安全凭据
+
+* **App ID**：cli\_xxxxxxxxxx
+* **App Secret**：xxxxxxxxxxxxxxxx
+
+**tenant_access_token**：是飞书开放平台中自建应用用于访问租户资源的凭证。最长访问时效是2小时。
+
+**数据资源URL中要求相关信息**：例如针对电子表格URL 中：<https://open.feishu.cn/open-apis/sheets/v2/spreadsheets/:spreadsheetToken/values/:range>
+
+* spreadsheetToken：电子表格的 token
+* Range：格式为<sheetId>!<开始位置>:<结束位置>。
+
+## 3. **云器lakehouse中导入飞书数据**
+
+### 方式一：使用python脚本导入飞书数据
+
+#### 步骤1：在云器Studio中创建Python任务
+
+1. 登录云器Lakehouse控制台
+2. 进入"开发" → "Python任务"
+3. 点击"新建任务"
+4. 配置任务信息：**任务名称**：飞书数据同步，**任务描述**：从飞书表格导入数据到Lakehouse
+
+#### 步骤2：配置代码参数
+
+```py
+import requests
+from sqlalchemy import text
+from clickzetta_dbutils import get_active_lakehouse_engine
+
+def get_feishu_token():
+    url = "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal"
+    data = {"app_id": "您自己的app_id", "app_secret": "xxxxxxxxxxxxx"}
+    response = requests.post(url, json=data, timeout=5)
+    return response.json()['tenant_access_token']
+
+def get_sheet_data(token):
+    url = "https://open.feishu.cn/open-apis/sheets/v2/spreadsheets/DuUHsqS6qh97i9tpNkYcoC84nHb/values/2729cf!A1:B2"
+    headers = {"Authorization": f"Bearer {token}"}
+    response = requests.get(url, headers=headers, timeout=5)
+    return response.json()['data']['valueRange']['values']
+
+def get_lakehouse_connection():
+    """
+    使用get_active_lakehouse_engine连接Lakehouse，无需用户在python中填写云器关联的账户信息
+    注意：vcluster参数是必填的
+    """
+    engine = get_active_lakehouse_engine(
+        vcluster="DEFAULT",  # 必填：虚拟集群名称
+        workspace="对应的工作空间名称",  # 可选：工作空间名称
+        schema="public"  # 可选：schema名称，默认为public
+    )
+    return engine
+
+def create_table():
+    """创建表：这里需要要求自己根据飞书表中的数据信息创建规范的table"""
+    engine = get_lakehouse_connection()
+    
+    create_sql = text("""
+    CREATE TABLE IF NOT EXISTS feishu_data (
+        name VARCHAR(255),
+        id BIGINT,
+        created_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+    )
+    """)
+    
+    with engine.connect() as conn:
+        conn.execute(create_sql)
+    
+    print("✅ 表创建成功")
+
+def insert_data(data):
+    """插入数据 """
+    engine = get_lakehouse_connection()
+    headers = data[0]  
+    rows = data[1:]   
+    
+    # 批量生成SQL
+    for i, row in enumerate(rows):
+        name = str(row[0]).replace("'", "''")  # 转义单引号
+        id_value = int(row[1])
+        
+        with engine.connect() as conn:
+            insert_sql = f"INSERT INTO feishu_data (name, id) VALUES ('{name}', {id_value})"
+            conn.execute(text(insert_sql))
+            print(f"✅ 插入第{i+1}行: {name}, {id_value}")
+    
+    print(f"✅ 数据插入完成，共{len(rows)}条记录")
+
+def verify_data():
+    """验证数据"""
+    engine = get_lakehouse_connection()
+    
+    with engine.connect() as conn:
+        result = conn.execute(text("SELECT * FROM feishu_data ORDER BY created_time DESC"))
+        rows = result.fetchall()
+        
+        print(f"\n📊 验证结果 (共{len(rows)}条记录):")
+        for row in rows:
+            print(f"  name: {row.name}, ID: {row.id}, 时间: {row.created_time}")
+
+if __name__ == "__main__":
+    print("🚀 飞书数据导入云器Lakehouse")
+    print("=" * 50)
+    
+    # 1. 获取飞书数据
+    print("\n📥 获取飞书数据...")
+    token = get_feishu_token()
+    print(f"Token获取成功: {token[:10]}...")
+    
+    data = get_sheet_data(token)
+    print("飞书数据获取成功:")
+    for i, row in enumerate(data):
+        print(f"  行{i+1}: {row}")
+    
+    # 2. 创建表
+    print(f"\n🔧 创建Lakehouse表...")
+    create_table()
+    
+    # 3. 插入数据
+    print(f"\n📝 插入数据...")
+    insert_data(data)
+    
+    # 4. 验证数据
+    print(f"\n🔍 验证结果...")
+    verify_data()
+    
+    print(f"\n🎉 任务完成！")
+```
+
+#### 步骤3：配置调度信息进行周期调度（可选）
+
+若需要定期从表中拉取数据，可直接配置该python任务的调度信息。
+
+例如：若需要每天早上8点定时拉取最新数据，则可进行如下配置
+
+1. 调度周期：每天调度
+2. 调度频率：执行一次、开始调度时间：08:00
+3. 生效日期：2025-06-11（希望任务开始运行的时间）
+
+![](.topwrite/assets/702bc8f656/0aabbf094597aaef2e4fcda3bb5a5f4cda9e35c8.png =300)
+
+### 方式二：使用离线任务的方式导入飞书数据
+
+当前离线任务的方式暂时不支持周期性抽取数据，只支持手动触发执行。
+
+#### 步骤1：获取tenant\_access\_token
+
+可使用python脚本获取**tenant\_access\_token**
+
+1. 登录云器Lakehouse控制台
+2. 进入"开发" → "Python任务"
+3. 点击"新建任务"
+
+配置任务信息：
+
+**任务名称**：获取飞书tenant_access_token
+
+```
+import requests  # 添加导入语句
+
+def get_feishu_token():
+    url = "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal"
+    data = {
+        "app_id": "cli_xxxxxxx",
+        "app_secret": "xxxxxxxxxxxxxx"
+    }
+    response = requests.post(url, json=data)
+    
+    # 添加错误处理（重要！）
+    if response.status_code != 200:
+        raise Exception(f"HTTP请求失败，状态码: {response.status_code}")
+    
+    json_data = response.json()
+    
+    # 检查飞书API返回的错误
+    if json_data.get("code") != 0:
+        raise Exception(f"飞书API错误: [{json_data.get('code')}] {json_data.get('msg')}")
+    
+    return json_data['tenant_access_token']
+
+# 调用函数并打印结果
+try:
+    result = get_feishu_token()
+    print(f"获取的租户访问令牌: {result}")
+except Exception as e:
+    print(f"获取token失败: {str(e)}")
+```
+
+^
+
+#### 步骤2：使用RestApi的方式创建飞书数据源
+
+1. 登录云器Lakehouse控制台
+2. 进入"管理-数据源"
+3. 新建数据源，选择RestApi
+
+> * 数据源名称：飞书数据
+> * URL地址：<https://open.feishu.cn/open-apis/sheets/v2/spreadsheets/>:**spreadsheetToken**/values/:**range**
+>   * spreadsheetToken：电子表格的 token
+>   * Range：格式为<sheetId>!<开始位置>:<结束位置>。参数信息可参考[飞书文档](https://open.feishu.cn/document/server-docs/docs/sheets-v3/data-operation/reading-a-single-range)
+> * 请求方式：GET
+> * KEY：Content-Type //固定值
+> * VALUE：application/json; charset=utf-8 //固定值
+> * 验证方法：不验证
+
+![](.topwrite/assets/702bc8f656/d60f2dd672cc92dd8344e17699256b288942d1e1.png =300)
+
+#### 步骤3：创建离线同步任务同步数据
+
+1. 登录云器Lakehouse控制台
+2. 进入"开发" → "离线同步"
+3. 点击"新建任务"
+
+> 来源目标配置：
+>
+> * 来源数据：选择同步的数据源：飞书数据。 数据源配置参考步骤2
+> * 请求参数：空
+> * 请求体：填写应用凭证  {   "app\_id": "cli\_xxxx",   "app\_secret": "xxxxxxxxxxxxxx"  }
+> * 请求头：key ：value  Content-Type：application/json; charset=utf-8  Authorization ：Bearer **tenant\_access\_token**
+> * 结果数据所处路径：你需要导入的数据的具体位置。可先不配置，通过点击预览数据确定数据位置后填写。
+>   &#x20; \-----------------------------------------------------------------------------------
+> * 目标数据：导入的数据地址。若是导入至云器lakehouse中，需先创建相应的table。（当前方式暂不支持快速建表）
+>   图例：数据对象表名为：test02\_feishu
+
+![](.topwrite/assets/702bc8f656/0c09f43f3b51860fa007c039db7a532a5a9f7cc5.png =300)
+
+字段映射配置：暂不支持嵌套数组格式的JSON解析，因此针对飞书API返回的数据，仅支持将value值以string类型导入至目标表中。
+| ------------------------------------------------------------------- |
+
+![](.topwrite/assets/702bc8f656/06c63b288c79f24b2781a479041ca4da24faf705.png =300)
+
+#### 步骤4：数据处理，将导入string字段处理成标准化表
+
+1. 前提：需要用户提前明确表结构。
+2. 登录云器Lakehouse控制台
+3. 进入"开发" → "SQL任务"
+4. 点击"新建任务"
+
+```
+-- 1. 创建目标表
+CREATE TABLE if not EXISTS test02_feishu_parsed (
+    name STRING,
+    id BIGINT
+);
+
+-- 2. 转换并插入数据
+INSERT INTO test02_feishu_parsed
+WITH parsed AS (
+    SELECT from_json(content, 'array<array<string>>') as arr
+    FROM test02_feishu
+    WHERE content IS NOT NULL
+),
+flattened AS (
+    SELECT explode(slice(arr, 2, size(arr))) as row_data
+    FROM parsed
+    WHERE size(arr) > 1
+)
+SELECT 
+    row_data[0] as name,
+    CAST(row_data[1] AS BIGINT) as id
+FROM flattened;
+
+-- 3. 查看结果
+SELECT * FROM test02_feishu_parsed;
+```
+
+## 4. **常见问题**
+
+### 问题1：使用python脚本和离线任务导入飞书数据的区别
+
+Python脚本导入：可支持定期调度飞书表格中的数据，但是需要用户熟悉Python语法。
+
+离线任务导入：提供无代码页面配置，操作门槛较低。但是当前暂不支持周期调度，后续版本会支持。
+
+### 问题2：开发过程中总是提示没有权限
+
+检查相关权限是否配置正确
+
+飞书应用中：是否是基于文件类型配置相应的权限。注意，url中sheet和wiki对应的权限都是有区别的，一定要选择正确的权限点。
+
+配置后是否发布审批：用户在配置权限后，还需点击发布，待管理员审批通过后才能获取权限点
+
+是否在飞书文档中为该应用配置了访问权限。此步骤非常重要！企业用户必须完成此配置才能通过API进行访问。

package/bin/skills/lakehouse-doc/references/774c65e217.md

@@ -0,0 +1,136 @@
+# 如何上传json/jsonl文件导入到lakehouse的表中
+
+^
+
+## 前提条件
+
+当前仅支持以下标准格式的json/jsonl文件，若不符合规范则无法成功识别
+
+**JSONL格式**
+
+> * 每行一个完整的JSON对象
+> * 行之间用换行符（\n）分隔
+> * 不允许行尾有逗号
+> * 每行必须是有效的JSON
+> * 支持标准格式化的JSON行
+>   -----示例1---
+>   {"id": 1, "name": "Alice", "age": 30, "city": "New York"}{"id": 2, "name": "Bob", "age": 28, "city": "Los Angeles"}{"id": 3, "name": "Charlie", "age": 35, "city": "Chicago"}{"id": 4, "name": "Diana", "age": 32, "city": "Houston"}
+>   -----示例2---
+>   {"id": 1, "name": "Alice", "age": 30, "city": "New York"}
+>   {
+>   "id": 2,
+>   "name": "Bob",
+>   "age": 28,
+>   "city": "Los Angeles"
+>   }
+
+**JSON格式**
+
+> --JSON数组格式---
+> [{"id": 1, "name": "Alice", "age": 30, "city": "New York"},{"id": 2, "name": "Bob", "age": 28, "city": "Los Angeles"},{"id": 3, "name": "Charlie", "age": 35, "city": "Chicago"},{"id": 4, "name": "Diana", "age": 32, "city": "Houston"}]
+> --JSON格式化---
+> {
+> "id": 2,
+> "name": "Bob",
+> "age": 28,
+> "city": "Los Angeles"
+> }
+
+## 方案一：使用云器lakehouse web端上传功能导入
+
+**操作步骤**：
+
+在如下地方均可以点击「上传数据」
+
+* 实例首页->数据上传
+* 开发->数据树左侧
+* 数据资产地图->数据上传
+* 数据资产地图->数据管理->数据树->数据上传
+
+将符合标准格式规范的，且后缀是json/jsonl的文件拖拽/添加至上传区域，同时选择具体的配置信息，详细操作可见 [数据上传](<upload_data.md>)
+
+
+**上传到新表**
+
+| ![](.topwrite/assets/774c65e217/dcc4141809b8624f9869df74f16143d62d0c4618.jpeg =290) | ![](.topwrite/assets/774c65e217/620b74b85135aaf3f07902fc33d9fa1c6ce62ae0.jpeg =475) |
+| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+
+当文件添加后，系统会给予json/jsonl的规则解析文件中的信息，并生成相应的字段名称、类型、以及具体的数值。
+
+当确定解析的信息准确无误后，可自定义勾选本次希望上传和导入的数据。
+
+点击确定后，系统会自动创建相应的表，同时将json文件的数据导入到该表中。
+
+**上传到已有表**
+
+| ![](.topwrite/assets/774c65e217/cd685005810b036910d46bd65780b5426676360e.png =259) | ![](.topwrite/assets/774c65e217/96a4ea3793bc69dedc0d9156a20b0d3a90df6167.jpeg =391) |
+| ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+
+* 选择目标表后，点击下一步，会列出目标表的具体字段。
+* 请确保目标文件中的数据有相应的字段信息，若存在字段和文件中字段不一致的场景，处理规则如下：
+* 若文件中没有目标表的字段，则该字段的数值默认为null
+* 若文件中有的字段没有在表中出现，则该字段默认不进行任何处理。
+* 若文件中的字段与表中的字段名一致，但是类型不一致，则该数值会被判定为错误数据。
+
+## 方案二：使用外部volume导入
+
+> 只支持每行是一个完整的JSON对象的形式导入，若文件中存在换行、格式化的场景，则无法解析。
+
+第一步：创建外部volume的链接
+
+```Plain
+```Plain
+CREATE STORAGE CONNECTION IF NOT EXISTS oss_test3   
+     TYPE oss    
+     ENDPOINT = '对应的endpoint'  
+     ACCESS_ID = '您的access_id'   
+     ACCESS_KEY = '您的access_key'   
+     COMMENTS = 'OSS public endpoint' ; 
+```
+
+第二步：创建外部volume
+
+```SQL
+CREATE EXTERNAL VOLUME  if not exists my_volume 
+LOCATION 'oss://json_file/' 
+USING CONNECTION oss_test3
+DIRECTORY = (enable=true, auto_refresh=true)
+RECURSIVE=true;
+```
+
+第三步：校验volume是否创建成功（可选）
+
+```Plain
+list VOLUME my_volume;
+```
+
+第四步：使用 sqlline 工具或 数据库管理工具。该命令暂不支持在 Studio 中运行。
+
+```Plain
+PUT '/Users/xxx/xxxx.json'  to  volume public.my_volume  file  'ods.json';
+```
+
+第五步：查询上传的json文件格式（可选）
+
+```Plain
+SELECT * FROM VOLUME my_volume  USING  json FILES('odst.json') LIMIT 5;
+```
+
+第六步：基于文件解析后的字段创建相应的lakehouse table（table创建过程略）并将数据导入到table中
+
+```Plain
+COPY INTO day_report_simple
+FROM VOLUME my_volume
+USING JSON
+FILES('ods.json');
+```
+
+QA
+
+问题一：使用数据上传功能上传的数据解析的字段不全
+
+使用数据上传功能默认只解析json中前1000行的字段信息，若1000行外的数据中有不同的key和value默认不会进行处理。
+
+问题二：为什么创建了CONNECTION和VOLUME但是依旧提示上传文件失败？
+
+当前在云器studio产品内，无法通过运行结果直接判断CONNECTION和VOLUME是否成功创建，建议参考方案二中的第三步判断是否创建成功。

package/bin/skills/lakehouse-doc/references/9164fed65a.md

@@ -0,0 +1 @@
+^

package/bin/skills/lakehouse-doc/references/AIGateway.md

@@ -0,0 +1,3 @@
+ 
+
+请参考 [AI Gateway](AI_Gateway.md)。

package/bin/skills/lakehouse-doc/references/AI_COMPLETE.md

@@ -0,0 +1,157 @@
+## AI\_COMPLETE
+
+`AI_COMPLETE` 是云器 Lakehouse 平台中用于生成式 AI 任务的核心标量函数。它允许用户在 SQL 环境中直接调用大规模语言模型（LLM），根据文本提示或多模态输入生成响应（补全），从而完成文本补全、翻译、情感分析、代码生成及复杂推理等任务。
+
+云器将 AI 计算下沉至存储层与执行引擎，确保数据在平台内部即可实现智能化处理，无需流转至外部环境，从而在保障数据安全的同时极大地降低了任务延迟。
+
+用户可以提供以下类型的输入：
+
+* **文本提示**：提供一个字符串形式的 Prompt，由模型生成响应。详见 AI\_COMPLETE（单字符串）。
+* **单张图像与文本提示**：提供一张图像和一个文本提示，由模型根据图像与提示生成响应。详见 AI\_COMPLETE（单图像）。
+
+### 语法
+
+该函数的语法取决于用户提供的输入类型：
+
+* AI\_COMPLETE（单字符串）
+* AI\_COMPLETE（单图像）
+
+## AI\_COMPLETE（单字符串）
+
+使用支持的语言模型，根据文本提示生成响应（补全）。
+
+### 语法
+
+sql
+
+```sql
+AI_COMPLETE(<model>,<prompt> [,<model_parameters>][,<response_format>][,<show_details>])
+```
+
+该函数包含 **2 个必需参数**和 **3 个可选参数**，支持位置参数语法和命名参数语法。
+
+### 参数说明
+
+**必需参数**
+
+\`\`（STRING）
+
+指定要调用的语言模型。模型的来源有两种：[模型管理](AI_Gateway.md) 中的**Endpoint** 和 **API Connection 连接对象**。在函数的第一个参数中，通过不同的前缀来区分模型来源。
+
+**来源一**：模型管理中的 Endpoint：
+
+模型管理是云器 Lakehouse 平台统一管理模型服务的网关层。在 API Gateway 中注册的模型可直接通过 `endpoint:` 前缀引用。
+
+**语法格式**：
+
+```scheme
+'endpoint:<endpoint名称>'
+```
+
+**使用示例**：
+
+```sql
+SELECT AI_COMPLETE('endpoint:lis_openai_llm','prompt string',GET_PRESIGNED_URL(VOLUME volume_name, '<relative_file_path>', <expiration_time>));
+```
+
+其中，`lis_openai_llm` 模型管理 endpoint 是由平台管理员在 API Gateway 中预先配置，包含模型供应商、模型版本、认证凭据等信息。普通用户无需关心底层连接细节，只需通过端点名称即可调用对应模型。
+
+***
+
+**来源二**：API Connection 连接对象
+
+API Connection 是用户在 Lakehouse 中自行创建的模型服务连接对象，适用于需要自定义模型服务地址、认证密钥或对接私有化部署模型的场景。通过 `CREATE API CONNECTION` 语句创建连接对象后，即可在 `AI_COMPLETE` 中引用。
+
+**创建连接对象语法**：
+
+sql
+
+```sql
+CREATE API CONNECTION <connection_name>
+    TYPE ai_function
+    PROVIDER = '<provider_name>'
+    BASE_URL = '<service_endpoint_url>'
+    API_KEY = '<your_api_key>';
+```
+
+**创建连接对象示例**：
+
+```sql
+CREATE API CONNECTION conn_bailian
+    TYPE ai_function
+    PROVIDER = 'bailian'
+    BASE_URL = 'https://dashscope.aliyuncs.com/api/v1'
+    API_KEY = 'sk-xxxxxxxxxxxxxxxxxxxxxxxx';
+```
+
+其中各字段含义如下：
+
+`connection_name` 为连接对象的自定义名称，后续在 `AI_COMPLETE` 中通过该名称引用；
+
+`TYPE` 固定为 `ai_function`，表示该连接用于 AI 函数调用；
+
+`PROVIDER` 指定模型供应商标识，如 `'bailian'`（百炼）、`'openai'`、`'anthropic'` 等；
+
+`BASE_URL` 为模型服务的 API 基础地址；`API_KEY` 为调用该服务所需的认证密钥。
+
+***
+
+**在 AI\_COMPLETE 中引用连接对象**：
+
+```sql
+SELECT AI_COMPLETE('connection:conn_bailian','请简要介绍量子计算的基本原理。');
+```
+
+**语法格式**：
+
+```scheme
+'connection:<连接对象名称>'
+```
+
+###
+
+### 示例
+
+**基础用法：单个文本提示**
+
+```
+SELECT AI_COMPLETE(
+    'endpoint:aliyun-qwen3max',
+    '中国的首都在哪里?'
+);
+
+```
+
+**图像识别**：
+
+使用支持的多模态语言模型，根据单张图像与文本提示生成响应（补全）。该模式适用于视觉问答（VQA）、图像内容描述、图像信息提取、OCR 识别等需要模型理解图像内容的场景。
+
+```
+SELECT 
+        a.id, 
+        a.question,
+        a.answer AS standard_answer,
+        -- 1. AI生成答案
+        ai_complete(
+            'endpoint:doubao-seed-2-0-pro-260215',
+            JSON_OBJECT(
+                'system', 'You are a VQA assistant. Answer based on the image in English. Be extremely concise (1-5 words).',
+                'user', a.question,
+                'images', ARRAY(CONCAT('volume://volumes/datagpt_ws/image_hub/my_images/', LPAD(CAST(a.id AS STRING), 11, '0'), '.jpg'))
+            )
+        ) AS ai_generated_answer,
+        -- 2. 生成图片预览URL
+        get_presigned_url(
+            VOLUME lakehouse_ai.image_hub.my_images,
+            LPAD(CAST(a.id AS STRING), 11, '0') || '.jpg',
+            7200  
+        ) AS image_preview_url,
+        -- 3. 图片存储路径
+        CONCAT('volume://volumes/lakehouse_ai/image_hub/my_images/', LPAD(CAST(a.id AS STRING), 11, '0'), '.jpg') AS image_path
+    FROM 
+        lakehouse_ai.image_hub.evjvqa_annotations_20 AS a
+```
+
+效果如下：
+
+![](/.topwrite/assets/ai_complete_pic.jpeg)