BigQuery AI.SIMILARITY 语义相似度计算完全指南：语法、参数与文本/图像匹配实战-迪斯科星球

BigQuery AI.SIMILARITY 语义相似度计算完全指南：语法、参数与文本/图像匹配实战

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills

本篇技术指南围绕bigquery-ai-mlAgent Skill 中的参考文档references/ai_similarity.md展开，系统讲解 BigQuery 内置函数AI.SIMILARITY的语法参考、输入参数、输出结构，以及如何用一段 SQL 完成“文本对文本”和“文本对图像”的语义相似度计算。读完后，你将能够直接在 SQL 查询中使用AI.SIMILARITY实现语义搜索与相似推荐，并结合仓库中的AI.SEARCH、VECTOR_SEARCH、AI.GENERATE_EMBEDDING等参考资料理解各方案之间的选型差异。

1. AI.SIMILARITY 的定位：在 bigquery-ai-ml Skill 中做什么

AI.SIMILARITY计算两个输入之间的语义相似度（semantic similarity）。根据参考文档 ai_similarity.md 的说明，它的典型使用场景包括：

语义搜索（Semantic search）：基于自然语言描述来检索文本或图像，而不需要匹配特定关键词；
推荐（Recommendation）：返回与某个给定实体属性相似的实体。

该文档是 BigQuery AI & ML Skill 的参考目录成员之一。SKILL.md 将AI.SIMILARITY归类为 "Semantic similarity" 参考，与AI.SEARCH（语义搜索）、VECTOR_SEARCH（向量检索）、AI.GENERATE_EMBEDDING（生成嵌入）等函数并列。BigQuery 通过与 Vertex AI 集成，在 SQL 查询中直接提供AI.FORECAST、AI.KEY_DRIVERS、AI.DETECT_ANOMALIES、AI.GENERATE等一系列内置 AI 函数，AI.SIMILARITY正是这一体系中用于相似度度量的标量函数。

从仓库结构看，skills/cloud/bigquery-ai-ml/references/目录下共包含 16 个函数参考文档（ai_agg.md、ai_classify.md、ai_similarity.md、ai_score.md、ai_search.md、vector_search.md、remote_models.md等），ai_similarity.md是其中专门覆盖相似度计算的参考文件。

2. 语法参考（Syntax Reference）

AI.SIMILARITY的完整调用签名如下（原文档完整保留）：

AI.SIMILARITY( content1 => 'CONTENT1', content2 => 'CONTENT2' [, endpoint => 'ENDPOINT'] [, model_params => 'MODEL_PARAMS'] [, connection_id => 'CONNECTION_ID'] )

可以看到，两个内容参数（content1、content2）使用命名参数（named argument）方式传入，而endpoint、model_params、connection_id三个为可选参数，用方括号[, ...]标注。

2.1 输入参数说明

参数	要求	类型	说明
`content1`	必填	String 或 ObjectRef	第一段文本内容或图像上下文
`content2`	必填	String 或 ObjectRef	与之比较的第二段文本内容或图像
`connection_id`	可选	String	用于 LLM 的 Connection ID
`endpoint`	可选	String	模型端点（例如`'text-embedding-005'`）
`model_params`	可选	JSON	模型参数的 JSON 对象（例如`temperature`、`max_output_tokens`）

几个值得注意的实现细节：

String or ObjectRef的双类型输入是AI.SIMILARITY支持多模态比较的关键。当内容来自 Cloud Storage 上的对象（图像文件）时，通过OBJ.MAKE_REF()等对象引用函数生成的ObjectRef值即可作为参数传入，这在第 4.2 节的图文比较示例中会用到。
endpoint指定底层嵌入模型。原文档给出的示例端点是'text-embedding-005'；在图文比较示例中则使用了'multimodalembedding@001'端点来处理图像输入。结合 remote_models.md 的说明，BigQuery 可用的嵌入类端点包括text-embedding-005、text-multilingual-embedding-002、gemini-embedding-001，生成类端点则包括gemini-2.5-pro、gemini-2.5-flash。也就是说，AI.SIMILARITY通过endpoint参数决定用哪个 Vertex AI 模型来计算相似度。
connection_id控制连接解析。同样依据 remote_models.md 的说明：当使用REMOTE WITH CONNECTION DEFAULT时，BigQuery 会自动尝试使用模型所在区域的默认连接；否则必须指定全限定连接 ID（格式如my-project.us.my-connection）。AI.SIMILARITY的connection_id参数即用于显式指定该连接。

2.2 输出结构（Output Schema）

列名	类型	说明
(标量结果)	`FLOAT64`	相似度分数（例如余弦相似度，cosine similarity）。出错时返回 null

AI.SIMILARITY是一个标量函数（scalar function），返回单行单列的FLOAT64分数，这与第 5 节要介绍的AI.SEARCH、VECTOR_SEARCH等**表值函数（table-valued function）**有本质区别：

标量语义意味着它可以嵌入到SELECT列表、WHERE子句或ORDER BY中，对任意两列/两行内容逐对打分，非常适合“逐行计算相似度后排序取 Top N”的写法；
错误时返回 null这一行为对数据管道很关键：查询不会因为个别无法处理的输入而整体失败，你可以在外层用WHERE score IS NOT NULL或COALESCE过滤失败行。

3. 实战示例一：两段文本的语义相似度

第一个示例计算两句自然语言的语义相似度。两句话用词完全不同（cat/feline、sat/resting、mat/rug），但语义相近，适合验证函数确实做的是“语义”匹配而非关键词匹配：

SELECT AI.SIMILARITY( content1 => 'The cat sat on the mat', content2 => 'A feline is resting on the rug' ) as similarity_score;

由于未指定endpoint和connection_id，此写法依赖 BigQuery 的区域默认连接行为（见 remote_models.md 中关于REMOTE WITH CONNECTION DEFAULT的说明）。若你的项目未配置默认连接，或想固定端点以保证结果一致性，应显式传入endpoint => 'text-embedding-005'与connection_id。

在真实业务中，更常见的用法是把字面量换成表中的列，例如比较两张商品表的描述文本：

-- 基于原文档语法的列级用法示意 SELECT p1.title AS title_a, p2.title AS title_b, AI.SIMILARITY(content1 => p1.description, content2 => p2.description) AS similarity FROM `mydataset.products` p1 JOIN `mydataset.products` p2 ON p1.sku <> p2.sku ORDER BY similarity DESC LIMIT 10;

4. 实战示例二：文本与图像的语义相似度

这是原文档给出的多模态示例，完整继承如下。它分三步：

创建 schemacymbal_pets；
创建一张外部表cymbal_pets.product_images，指向 Cloud Storage 上gs://cloud-samples-data/bigquery/tutorials/cymbal-pets/images/的 PNG 图片；
用AI.SIMILARITY将查询文本"aquarium device"与每张图片（ObjectRef）逐一比较，按相似度降序取 Top 3，并用OBJ.GET_READ_URL生成签名 URL 方便人工查看命中结果。

CREATE SCHEMA IF NOT EXISTS cymbal_pets; CREATE OR REPLACE EXTERNAL TABLE cymbal_pets.product_images WITH CONNECTION DEFAULT OPTIONS ( object_metadata = 'SIMPLE', uris = ['gs://cloud-samples-data/bigquery/tutorials/cymbal-pets/images/*.png'] ); SELECT uri, OBJ.GET_READ_URL(ref) AS signed_url, ai.similarity( "aquarium device", ref, endpoint => 'multimodalembedding@001') AS similarity_score FROM cymbal_pets.product_images ORDER BY similarity_score DESC LIMIT 3;

从这段示例可以提炼出几个实操要点：

外部表 + ObjectRef：CREATE EXTERNAL TABLE ... OPTIONS (object_metadata = 'SIMPLE', uris = [...])让 BigQuery 为每个对象暴露uri和ref列，ref即ObjectRef类型，可直接作为AI.SIMILARITY的图像输入；
endpoint => 'multimodalembedding@001'：图像比较必须使用能理解图像的多模态嵌入端点，这与纯文本场景默认使用的text-embedding-005不同。从该示例可以推断，处理图像输入时应显式指定多模态端点，而不是依赖默认端点；
WITH CONNECTION DEFAULT：外部表同样可以走默认连接，与AI.SIMILARITY的connection_id缺省行为保持一致的连接解析逻辑；
结果可验证性：signed_url列让你可以直接打开排名靠前的图片确认“aquarium device（水族箱设备）”这一查询是否真的排到了相关产品，这是调试语义检索质量时的实用技巧。

5. 选型对比：AI.SIMILARITY 与 AI.SEARCH / VECTOR_SEARCH

同一个 Skill 仓库中，ai_search.md 和 vector_search.md 也覆盖了“找相似”这一主题，三者定位不同，选型时应结合数据形态决定：

维度	`AI.SIMILARITY`	`AI.SEARCH`	`VECTOR_SEARCH`
函数形态	标量函数，返回`FLOAT64`	表值函数，返回`base`+`distance`	表值函数，返回`base`+`distance`（批量检索还含`query`）
输入	任意两个文本/图像内容（字面量或列）	表（需启用 autonomous embedding）+ 查询字符串	基表 + 查询表/查询向量
典型用法	逐对打分、条件过滤、Top-N 排序	对启用自动嵌入的表做语义检索/推荐/聚类/离群检测	对已有嵌入列做最近邻检索，支持`top_k`（默认 10）、`distance_type`（`EUCLIDEAN`/`COSINE`/`DOT_PRODUCT`，默认`EUCLIDEAN`，官方建议用`COSINE`）
嵌入来源	由`endpoint`指定的模型在查询时计算	表的`generated_expression`（`AI.EMBED(source_column)`）	基表的嵌入列，或运行时嵌入

简化的选型思路：

你有任意两段内容（包括图像）想给它们打个相似度分数，或想在WHERE/ORDER BY中做逐行比较 → 用AI.SIMILARITY；
你有一张启用了 autonomous embedding 的表，想按查询词直接取回 Top-K 相似行 → 用AI.SEARCH；
你已经维护了嵌入列（例如通过 AI.GENERATE_EMBEDDING 生成，其输出为ARRAY<FLOAT64>的embedding列）→ 用VECTOR_SEARCH做最近邻检索。

从 ai_search.md 的建表示例还可以看到 autonomous embedding 的写法：列定义为GENERATED ALWAYS AS (AI.EMBED(description, connection_id => 'us.example_connection', endpoint => 'text-embedding-005')) STORED OPTIONS(asynchronous = TRUE)。这说明AI.SIMILARITY的endpoint/connection_id参数与AI.EMBED使用同一套模型与连接体系，两者在配置层面是可对齐的。

6. 使用前提与注意事项

结合本仓库文档，使用AI.SIMILARITY时需要确认以下前提：

连接（Connection）：AI.SIMILARITY依赖 BigQuery 与 Vertex AI 的集成。若项目已配置区域默认连接，可省略connection_id；否则应传入全限定连接 ID（my-project.us.my-connection格式，见 remote_models.md）。
端点（Endpoint）：文本场景可显式使用text-embedding-005；图像输入参考文档示例使用multimodalembedding@001。显式指定端点可以避免依赖默认行为，也让结果在不同环境间更可复现。
model_params为 JSON：可传入temperature、max_output_tokens等模型参数，用于微调底层模型行为（原文档未给出具体的推荐取值，实际以端点支持的参数为准）。
错误处理：相似度计算失败时该行的结果为null而非抛出异常，管道中应显式处理。
适用边界：AI.SIMILARITY属于“在查询内计算”的函数，适合对少量成对内容打分或对中小规模表做逐行比较；对大规模表的 Top-K 检索，ai_search.md 与 vector_search.md 描述的表值函数方案（配合嵌入索引与top_k参数）是更直接的检索原语。

7. 小结与延伸阅读

AI.SIMILARITY是一个轻量、标量、多模态的语义相似度函数：两个必填内容参数（String 或 ObjectRef）、三个可选参数（endpoint、model_params、connection_id），返回FLOAT64分数且错误时为null。原文档给出的两个示例分别覆盖了“文本-文本”和“文本-图像”两条路径，配合本文的选型对比，可以直接用于语义搜索与推荐场景。

延伸阅读（均在当前仓库内）：

ai_similarity.md：本文的主体参考文档
ai_search.md：AI.SEARCH语义搜索与 autonomous embedding 建表
vector_search.md：VECTOR_SEARCH最近邻检索
ai_generate_embedding.md：AI.GENERATE_EMBEDDING嵌入生成
remote_models.md：远程模型创建、可用端点与连接使用方式
SKILL.md：BigQuery AI & ML Skill 的完整函数参考目录

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析