
用 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 卷上的文件,因此需要对相应卷有读权限。
先想清楚用哪一类函数
选型按三步走,能省掉大量评估与提示词维护工作:
- 任务特化型函数:抽取、分类、摘要、翻译、情感分析等定型处理,先看这里有没有现成的。
- ai_gen:不想指定模型、只想让模型回答一段自由提示词时使用。
- ai_query:需要控制提示词、模型、参数、输出格式,或要调用自定义模型、微调模型、外部模型时使用。
实践上,一开始就写 ai_query 提示词往往不如先确认任务特化型函数是否够用——后者的评估成本和长期维护成本都更低。
操作步骤
第一步:按目的挑函数
| 想做的事 | 使用的函数 | 要点 |
|---|---|---|
| 从 PDF、图片中取出文字与表格 | ai_parse_document | 保留版面结构做结构化,结果可在 Document Parsing 界面核对 |
| 从发票、合同中抽取字段 | ai_parse_document → ai_extract | 用 schema 定义字段与类型,可返回置信度与抽取来源位置 |
| 对工单、评论做分类 | ai_classify | 给标签加说明以传达判定标准,支持多标签 |
| 情感判定、摘要、翻译、脱敏 | ai_analyze_sentiment / ai_summarize / ai_translate / ai_mask | 直接传列,不需要提示词也不需要选模型 |
| 把内部文档用于检索或 RAG | ai_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 的函数(包括检索准备、异常检测、归因分析、预测类函数等)需要工作区管理员在预览中启用,接口与行为可能调整,不建议直接压在生产关键路径上。