AB
AiBoss站
教程

用 Databricks SQL 的 AI 函数对整表数据调用大模型

教程

用 Databricks SQL 的 AI 函数对整表数据调用大模型

Databricks 的 AI 函数让你用一行 SQL 就把大模型或专用 AI 应用到表的每一行:解析文档、抽取字段、分类、翻译、情感分析,或通过 ai_query 自选模型与提示词。本教程按「先选函数、再写查询、最后管权限与费用」的顺序,给出可直接运行的 SQL 与 REST 调用示例。

Databricks 的 AI 函数(AI Functions)是一组可以在 SQL 里直接调用的函数,用来把大模型或专用 AI 模型应用到一张表的每一行上。它的价值在于:分析师在 SQL 编辑器里试出来的一个函数调用,可以原样搬进生产批处理,不需要另写 Python 脚本、也不需要自己搭一套外部 API 调用链路。适合的对象是那些正在用脚本或外部接口逐条处理工单分类、发票读取、文本摘要的工程师与数据负责人——你不需要替换现有的数据平台或应用,只要对 Databricks 里已有的表(或已导入的文件)先试一个函数即可。

整套能力可以分成两条路线:任务特化型函数负责抽取、分类、摘要、翻译这类定型处理,不用写提示词、不用选模型;ai_query 是通用入口,提示词、模型、参数、输出格式都由你自己控制。查询在调用方的计算资源上执行,推理的并行化、重试与扩缩容由平台自动处理。权限上通过 system.ai 模式的 EXECUTE 权限按函数粒度限制使用,费用可以通过 system.billing.usage 查看。

准备工作

运行环境要求

  • AI 函数可以在 Databricks SQL(SQL 编辑器、仪表盘查询)、笔记本(SQL 单元格或经 spark.sql)、Lakeflow 管道(作为摄取时的转换逻辑)、以及作业中调用。
  • Classic SQL 仓库不支持这些函数,需要改用支持的计算类型。
  • 运行时版本要求 Databricks Runtime 15.4 LTS 及以上;若要使用最新功能与性能,建议 18.2 以上。
  • 部分函数只在特定区域可用,跨区域使用前先确认目标函数在你所在区域是否开放。
  • 部分函数标注为 Beta,需要工作区管理员在预览中启用后才能使用。

权限与账号

  • 调用任务特化型函数需要 system.ai 模式的 EXECUTE 权限。默认情况下所有用户都持有该权限,管理员可以按函数收回,从而限制哪些函数可以被谁使用。
  • 调用 ai_query 时,执行者对目标模型服务端点需要具备 CAN QUERY 权限。
  • 如果从 Databricks Apps 调用,需要给应用授予 ai-functions 与 files 两个 scope。
  • 文档类函数读取的是 Unity Catalog 卷上的文件,因此需要对相应卷有读权限。

先想清楚用哪一类函数

选型按三步走,能省掉大量评估与提示词维护工作:

  1. 任务特化型函数:抽取、分类、摘要、翻译、情感分析等定型处理,先看这里有没有现成的。
  2. ai_gen:不想指定模型、只想让模型回答一段自由提示词时使用。
  3. ai_query:需要控制提示词、模型、参数、输出格式,或要调用自定义模型、微调模型、外部模型时使用。

实践上,一开始就写 ai_query 提示词往往不如先确认任务特化型函数是否够用——后者的评估成本和长期维护成本都更低。

操作步骤

第一步:按目的挑函数

r>
想做的事使用的函数要点
从 PDF、图片中取出文字与表格ai_parse_document保留版面结构做结构化,结果可在 Document Parsing 界面核对
从发票、合同中抽取字段ai_parse_document → ai_extract用 schema 定义字段与类型,可返回置信度与抽取来源位置
对工单、评论做分类ai_classify给标签加说明以传达判定标准,支持多标签
情感判定、摘要、翻译、脱敏ai_analyze_sentiment / ai_summarize / ai_translate / ai_mask直接传列,不需要提示词也不需要选模型
把内部文档用于检索或 RAGai_parse_document → ai_prep_search → ai_search生成检索用分块,并接到带依据的回答上
销售额预测、异常检测ai_forecast / ai_detect_anomalies面向时间序列而非 LLM,会返回预测区间
自定义指令、输出格式、推理ai_query + responseFormat自选提示词与模型,把输出类型固定下来
让模型看图判断ai_query(files => content)需指定支持图像输入的模型,仅支持 JPEG 与 PNG
把自研 ML 模型应用到全表ai_query(自定义模型)调用部署在 Model Serving 上的模型

按类别看,函数大致分布如下:文档处理有 ai_parse_document、ai_extract、ai_classify、ai_prep_search、ai_search、ai_enrich;文本转换有 ai_fix_grammar、ai_translate、ai_summarize、ai_mask;文本分析有 ai_analyze_sentiment、ai_similarity、ai_decide;生成有 ai_gen;预测有 ai_predict_class、ai_predict_value;时间序列有 ai_forecast、ai_detect_anomalies;指标变化归因有 ai_top_drivers;通用入口是 ai_query。其中 ai_prep_search、ai_search、ai_enrich、ai_decide、ai_detect_anomalies、ai_top_drivers、ai_predict_class、ai_predict_value 属于 Beta,可用性以官网当前信息为准。

第二步:用任务特化型函数跑通一行 SQL

最简单的形态是直接把列传给函数。情感分析:

SELECT review_id,
       ai_analyze_sentiment(review) AS sentiment
FROM reviews;

文本类函数的签名与用途如下:

函数与参数作用典型场景
ai_analyze_sentiment(content)判定文本情感汇总商品评价的正负倾向
ai_similarity(str1, str2)两个字符串的语义相似度分数把写法不统一的公司名做归并
ai_summarize(content [, max_words])文本摘要把长工单压缩成要点列表
ai_translate(content, to_lang)翻译到指定语言把其他语种的咨询转成中文
ai_fix_grammar(content)修正语法错误整理用户输入的文字
ai_mask(content, labels)遮蔽指定类型的信息隐去姓名、电话后再共享
ai_gen(content)回答提示词回答非定型的问题

第三步:解析文档

文档处理由四个函数串起来:解析(ai_parse_document)、抽取(ai_extract)、分类(ai_classify)、判断(ai_decide,Beta)。解析时用 READ_FILES 读取卷上的文件,把二进制内容原样传入:

SELECT path,
       ai_parse_document(content) AS doc
FROM READ_FILES('/Volumes/main/default/contracts/', format => 'binaryFile');

输出是 VARIANT,包含页码、标题、表格、页脚等版面元素,以及其中的正文与表格数据;v2 版本中表格以 HTML 表示。处理在 Databricks 的安全边界内完成,传给函数的参数不会被保存(执行的元数据会保留)。结果可以在 Document Parsing 界面里把原始文档与解析结果并排比对,确认哪个区域抽出了什么。

第四步:按 schema 抽取字段

把要抽取的字段写成 JSON schema 传入。下面这个例子以发票列为输入:

SELECT invoice_file,
       ai_extract(
         body,
         '{"invoice_id": {"type": "string"},
           "vendor_name": {"type": "string"},
           "total_amount": {"type": "number"},
           "invoice_date": {"type": "string", "description": "YYYY-MM-DD"}}',
         options => map('version', '2.1',
                        'enableConfidenceScores', 'true')
       ) AS extracted
FROM invoices;

返回的 VARIANT 里,每个字段都带值与置信度:

{
  "response": {
    "invoice_id":   {"value": "12345",     "confidence_score": 0.95},
    "vendor_name":  {"value": "Acme Corp", "confidence_score": 0.62},
    "total_amount": {"value": 1250.00,     "confidence_score": 1.0},
    "invoice_date": {"value": "2024-01-15", "confidence_score": 0.99}
  },
  "error_message": null
}

常用选项有四个:instructions 传入任务或业务说明以提升精度(两万字以内);mode 设为 precision 时针对长文、大量字段、复杂 schema 做优化;enableCitations 返回抽取来源位置(字符区间或 PDF 上的坐标);enableConfidenceScores 返回每个字段 0 到 1 的置信度。

第五步:做分类

给标签加上说明,等于把判定标准告诉模型。multilabel 设为 true 时返回所有命中的标签,默认只返回一个:

SELECT ticket_id,
       ai_classify(
         body,
         '{"billing_error": "Payment, invoice, or refund issues",
           "product_defect": "Any malfunction, bug, or breakage",
           "account_issue": "Login failures, password resets"}',
         map('multilabel', 'true')
       ) AS category
FROM support_tickets;

Version 2 / 2.1 的限制:标签数量 2 到 500 个;每个标签说明最多 1,000 字符;instructions 长度两万字以内;输入整体 token 上限 100 万。v2 及以后版本不能在 Classic SQL 仓库和视图中使用。标签超过 500 个时需要另走其他方案。

第六步:需要自定义时改用 ai_query

ai_query 是专用函数不够用时的通用出口。参数含义如下:

参数内容补充
endpoint基础模型、外部模型或自定义模型的端点名执行者需要 CAN QUERY 权限
request发给模型的请求基础模型用 STRING;自定义模型用列或 STRUCT
returnType期望的返回类型DBR 15.2 以上会从模型 schema 自动推断
failOnError单行出错时是否中止整个查询默认 true;设为 false 时返回含响应与错误的 STRUCT
modelParameters温度等模型设置只能传常量;temperature 默认 0.0
responseFormat指定输出格式仅聊天基础模型支持,可用 DDL 形式或 JSON 形式
files图像输入(多模态)仅支持 JPEG 与 PNG

一个带结构化输出与容错的最小写法:

SELECT ticket_id,
       ai_query(
         'system.ai.gpt-oss-20b',
         'Extract product and issue: ' || body,
         responseFormat => 'STRUCT<result:STRUCT<product:STRING, issue:STRING>>',
         failOnError => false
       ) AS r
FROM support_tickets;

把结果存成表(例如 extracted)之后,可以只挑出失败的行:

SELECT ticket_id, r.errorMessage
FROM extracted
WHERE r.errorMessage IS NOT NULL;

只重跑这些行,就不必把已经成功的行再处理一遍。

第七步:选模型

模型来源分四类:

  • Databricks 提供的模型:system.ai 下的模型服务,涵盖 Claude、GPT-OSS、Llama、Qwen、Gemma 等,无需准备,自动扩缩容,优先从这里选。OpenAI 与 Gemini 只能经 ADI Services 使用。
  • 预置吞吐:微调过的基础模型等,需要先创建端点;批处理时由 AI 函数侧管理扩缩容。
  • 外部模型:托管在 Databricks 之外的模型,需要创建外部模型端点。
  • 自定义模型:自研的传统 ML / DL 模型,部署到 Model Serving 后即可从 SQL 调用。

批处理场景下,模型名以 system.ai. 开头指定,例如 system.ai.gpt-oss-120b、system.ai.gpt-oss-20b、system.ai.meta-llama-3-3-70b-instruct、system.ai.meta-llama-3-1-8b-instruct、system.ai.llama-4-maverick、system.ai.qwen35-122b-a10b、system.ai.qwen3-next-80b-a3b-instruct、system.ai.gemma-3-12b,以及 Claude 系列与嵌入模型 system.ai.gte-large-en、system.ai.qwen3-embedding-0-6b。具体可用型号、区域覆盖与命名以官网当前信息为准。

选模型的顺序:先按输入类型筛(文本用聊天模型,图像用支持图像输入的模型,检索向量用嵌入模型);再从面向批处理优化过的模型里挑两三个候选,未优化的模型吞吐会明显下降;然后用几百行带标注的样本对比精度、耗时与费用;最后把 modelParameters 与 responseFormat 固定下来。简单任务(短文本分类、抽取、摘要)先用小而快的模型验证精度,跨长文档判断或需要组合多个条件的推理再纳入大模型比较。

第八步:从应用里调用 REST API

需要逐件实时处理时,可以把同一批函数通过 REST API 调用。典型流程是:上传到 Unity Catalog 卷 → 解析 → 抽取 → 只把低置信度或无依据的字段交给人工确认 → 保存结果。接口调用顺序如下:

# 1. 上传到 Unity Catalog 卷
PUT /api/2.0/fs/files/Volumes/main/docs/inbox/inv.pdf

# 2. 解析
POST /api/2.0/ai-functions/ai-parse-document
{"content": "/Volumes/main/docs/inbox/inv.pdf"}

# 3. 抽取字段
POST /api/2.0/ai-functions/ai-extract
{"content": <parsed_document>,
 "schema": {"invoice_id": {"type": "string"},
            "total_amount": {"type": "number"}},
 "options": {...}}

options 里指定 version 2.1、引用与置信度;具体键名以 REST API 参考为准。应用侧自行实现「哪些字段需要人工确认」的判定逻辑,再把确认后的值与原始抽取结果一起写入表。

一个完整示例

下面把发票处理从文件到结构化结果串成一条最小可跑通的链路。假设发票 PDF 已放在 /Volumes/main/default/invoices/。

1. 解析全部发票文件

CREATE OR REPLACE TABLE parsed_invoices AS
SELECT path,
       ai_parse_document(content) AS doc
FROM READ_FILES('/Volumes/main/default/invoices/', format => 'binaryFile');

2. 按 schema 抽取关键字段,并打开置信度

CREATE OR REPLACE TABLE extracted_invoices AS
SELECT path,
       ai_extract(
         doc,
         '{"invoice_id": {"type": "string"},
           "vendor_name": {"type": "string"},
           "total_amount": {"type": "number"},
           "invoice_date": {"type": "string", "description": "YYYY-MM-DD"}}',
         options => map('version', '2.1',
                        'enableConfidenceScores', 'true',
                        'enableCitations', 'true')
       ) AS extracted
FROM parsed_invoices;

3. 按业务分类体系判定发票类型

CREATE OR REPLACE TABLE classified_invoices AS
SELECT path,
       ai_classify(
         CAST(extracted AS STRING),
         '{"purchase": "Goods purchased from a supplier",
           "service": "Consulting, maintenance, or other services",
           "travel": "Transport, lodging, or meals"}'
       ) AS invoice_type
FROM extracted_invoices;

4. 对需要复核的字段做二次判断

置信度低的字段可以交给 ai_query 用更明确的提示词再判一次,并把输出固定成 STRUCT:

SELECT path,
       ai_query(
         'system.ai.gpt-oss-20b',
         'Decide whether this invoice needs manual review. Answer yes or no: '
           || CAST(extracted AS STRING),
         responseFormat => 'STRUCT<result:STRUCT<needs_review:STRING>>',
         failOnError => false
       ) AS review
FROM extracted_invoices;

5. 只挑出失败行重跑

SELECT path, review.errorMessage
FROM review_results
WHERE review.errorMessage IS NOT NULL;

这条链路里,解析、抽取、分类三步都用了任务特化型函数,只有需要自定义判定标准的地方才引入 ai_query。整条链路可以放进作业里定期执行,新到的发票只需处理新增文件。

注意事项

文档处理的容量上限

项目上限
REST API 单文档页数100 页
SQL 调用单文档页数500 页
文件大小100 MB
REST API 默认请求上限每分钟 250 次(按工作区计,可申请提高)

处理非英文版式(例如日文票据)时,页数上限尤其要先确认。稳妥的做法是先把手上真实的几十份文档过一遍界面,看清识别质量再开始设计。

批处理的几个坑

  • 不要手动切分数据:并行化、重试与扩缩容都是自动的,自己把数据拆成小批反而会拉低吞吐。
  • 大批量时关掉 failOnError:让作业在部分行失败的情况下仍能完成,把成功结果保留下来,只重跑失败行。
  • 优先用面向批处理优化的模型:未优化的模型吞吐下降、处理时间拉长,候选模型清单以官网当前信息为准。
  • temperature 默认是 0.0:需要稳定可复现的输出时保持默认,不要随意调高。
  • modelParameters 只能传常量:不能按行传入不同的参数值。
  • responseFormat 只对聊天基础模型生效:自定义模型与嵌入模型不适用。
  • 图像输入只支持 JPEG 与 PNG:其他格式需要先转换。

权限与费用

  • 默认所有用户都持有 system.ai 的 EXECUTE 权限。要按函数限制使用范围,需要管理员主动收回。
  • 费用通过 system.billing.usage 查看,建议在批量上线前先在小样本上估算单行成本。
  • 调用 ai_query 时执行者必须对端点有 CAN QUERY 权限,否则查询会直接失败。
  • 具体价格、配额与各函数的区域可用性会变化,一律以官网当前信息为准。

Beta 功能

标注为 Beta 的函数(包括检索准备、异常检测、归因分析、预测类函数等)需要工作区管理员在预览中启用,接口与行为可能调整,不建议直接压在生产关键路径上。