企业官网建设流程全解析

ADK 中的 BigQuery AI.SIMILARITY：使用 SQL 计算文本余弦相似度的完整指南

【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python

本文聚焦 ADK 开源项目内置bigquery-ai-mlSkill 所封装的AI.SIMILARITY函数，系统讲解其语法、参数语义、输出约定与典型调用方式。在 ADK 场景中，该 Skill 通常配合SkillToolset与BigQueryToolset一起注入 Agent，让 Agent 通过标准的execute_sql()直接执行AI.SIMILARITY完成文本语义相似度计算。读完本文，你将掌握该函数的完整调用契约，并能在自己的 ADK Agent 中复现一套可运行的最简集成。

一、背景：bigquery-ai-ml Skill 与 AI.* 函数体系

在 ADK 仓库中，BigQuery 的 AI/ML 能力被封装为一个预置 Skill：bigquery-ai-ml。该 Skill 的核心设计原则是：优先使用标准 SQL 中的AI.*函数（通过execute_sql()执行），而不是为 Forecasting、Anomaly Detection 等功能引入专用高层工具。AI.SIMILARITY正是这套AI.*函数家族中的一员，与其并列的还有：

值得注意的是，SKILL.md 明确要求 Agent在生成 SQL 之前必须读取对应的参考文件（即references/目录下的 markdown），并强调“不要猜测文件名，只能使用精确路径”。本文讲解的 bigquery_ai_similarity.md 正是AI.SIMILARITY的强制参考文件。

二、AI.SIMILARITY 的功能与适用场景

AI.SIMILARITY是一个标量函数：它接收两个输入，返回二者之间的余弦相似度（cosine similarity）得分。

余弦相似度是衡量两个向量方向一致程度的经典度量，取值通常落在[-1, 1]区间（在文本嵌入场景中一般表现为非负值）：值越接近 1，表示两个输入在语义上越相近；越接近 0（或负值），表示语义差异越大。放在检索/Embedding 场景下，该函数由 LLM/嵌入模型在内部将两个文本输入转换为向量表示，再计算夹角余弦，从而将“两段文本是否语义相近”这一主观判断转化为一个可排序、可过滤的数值。

典型应用方向包括：

• 文本去重：判断两条客服工单、评论或商品描述是否表述相似；
• 相似内容匹配：从给定语料中找出与目标文本语义最接近的条目；
• 质量校验：验证模型生成结果与期望答案的语义一致性；
• 作为AI.SCORE（对整表逐行打分排序）与AI.SEARCH（表值函数，返回最近邻）的补充——当你只需要一对输入的相似度数值，而不是在一张表上做批量排序/搜索时，AI.SIMILARITY是最直接的选择。

三、完整语法参考

AI.SIMILARITY使用命名参数（named argument）风格调用，完整语法如下：

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

关键调用要点：

• content1与content2是两个待比较的文本内容；
• endpoint指定用于生成嵌入的模型端点（参考文档给出的示例值为'multimodalembedding@001'）；
• model_params以 JSON 字符串形式传递模型级参数（如temperature、max_output_tokens）；
• connection_id用于指定 BigQuery 连接，供底层 LLM/嵌入模型访问使用。

四、输入参数详解

对关键参数的进一步说明：

• content1/content2：二者均为必填的字符串。调用时直接传入字面量、列引用或表达式均可，函数内部会将其交由端点模型编码为向量后再计算余弦相似度。
• endpoint：决定使用哪个嵌入/多模态模型。参考文档给出的示例为'multimodalembedding@001'（多模态嵌入端点）；在与本文同目录的 bigquery_ai_search.md 中，还能看到使用'text-embedding-005'文本嵌入端点的示例。端点是否配置会直接影响向量表示的质量，因此在做文本语义比较时应优先选用专门的文本嵌入端点。
• model_params：以 JSON 字符串传递模型推理参数。参考文档明确给出的示例键包括temperature与max_output_tokens。实际可用键取决于所选端点的模型能力。
• connection_id：用于指定 BigQuery 连接（格式如'my-project.us.my-connection'）。当端点模型需要外部凭据或位于特定项目/区域时使用；对于通过预配置默认端点即可工作的场景可以省略。

五、输出 Schema

AI.SIMILARITY是标量函数，直接返回单个FLOAT64值，而非表或结构体。这一点与表值函数AI.SEARCH（返回baseSTRUCT 与distanceFLOAT64 两列）形成鲜明对比。同时请注意其容错约定：当计算出错（如端点不可用、输入非法）时，函数返回NULL而不是抛出异常，因此在 SQL 中通常需要配合COALESCE或WHERE ... IS NOT NULL来兜底。

六、实战示例

6.1 基础用法：比较两段文本的语义相似度

参考文档给出的标准示例：

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

该查询返回一列名为similarity_score的FLOAT64标量。两句话字面不同（“猫坐在垫子上”与“一只猫科动物正躺在毯子上”），但在语义上高度相关，因此预期得分接近 1。

6.2 指定连接与模型参数

当模型需要显式连接、或需要调节推理参数时，可将connection_id与model_params一并传入：

SELECT AI.SIMILARITY( content1 => 'A product review praising battery life', content2 => 'This laptop lasts 12 hours on a single charge', endpoint => 'text-embedding-005', connection_id => 'my-project.us.my-connection', model_params => '{"temperature": 0, "max_output_tokens": 256}' ) AS similarity_score;

6.3 与表数据结合：逐行对比两列

content1/content2可以是列引用，方便在表上做逐行相似度计算：

SELECT id, AI.SIMILARITY( content1 => question, content2 => answer, endpoint => 'text-embedding-005' ) AS qa_similarity FROM `my_dataset.support_pairs` WHERE AI.SIMILARITY( content1 => question, content2 => answer, endpoint => 'text-embedding-005' ) IS NOT NULL;

6.4 与 AI.SCORE 的分工

如果你需要在一张表内对每一行按其与某个目标的语义相关度打分并排序，应使用同族函数AI.SCORE，其典型形态为：

SELECT * FROM `dataset.table` ORDER BY AI.SCORE( (content_column, 'relevance to sports'), connection_id => 'my-project.us.my-connection' ) DESC LIMIT 10;

对比可见：AI.SIMILARITY回答“这两个输入有多像”，AI.SCORE回答“这张表里哪些行最相关”，二者互补而非重复。更进一步的批量语义检索则应使用表值函数AI.SEARCH，它在启用自动向量生成的表上工作，并支持top_k、distance_type（EUCLIDEAN / COSINE / DOT_PRODUCT）与options（如use_brute_force）等参数。完整参考见 bigquery_ai_score.md 与 bigquery_ai_search.md。

七、在 ADK Agent 中落地：SkillToolset + BigQueryToolset 集成

AI.SIMILARITY作为 SQL 函数，天然通过 BigQuery 的execute_sql()能力执行。在 ADK 中，bigquery-ai-mlSkill 的加载入口是 bigquery_skill.py 中的get_bigquery_skill()，它从skills/bigquery-ai-ml目录加载 Skill 定义；执行 SQL 的能力则来自BigQueryToolset。

按照 bigquery_skill.py 中的集成示范，一个最简的 Agent 装配如下：

from google.adk.agents import LlmAgent from google.adk.tools.bigquery import BigQueryToolset from google.adk.tools.bigquery.bigquery_skill import get_bigquery_skill from google.adk.tools.skill_toolset import SkillToolset bq_skill = get_bigquery_skill() toolset = SkillToolset(skills=[bq_skill]) bigquery_toolset = BigQueryToolset(...) # 传入凭据与工具配置 agent = LlmAgent( name="bigquery_agent", model="gemini-2.5-flash", tools=[bigquery_toolset, toolset], )

装配完成后，Agent 在收到“计算这两句话的相似度”之类的请求时，会按照 SKILL.md 的强制路由规则先读取references/bigquery_ai_similarity.md，再通过execute_sql()生成并执行上述AI.SIMILARITYSQL。

从源码看，BigQueryToolset在 bigquery_toolset.py 中注册了query_tool.get_execute_sql(...)等一批工具，并支持通过tool_filter精确裁剪暴露给 Agent 的工具集；而 bigquery_skill.py 会向前兼容地发出DeprecationWarning，提示google.adk.tools.bigquery下的实现已迁移至google.adk.integrations.bigquery，集成时建议以迁移后的路径为准。

八、最佳实践与注意事项

1. 先读参考文件再生成 SQL：bigquery-ai-mlSkill 的机制要求 Agent 在调用AI.*函数前必须读取对应的references/*.md文件，且只能使用精确路径，不能猜测文件名。这是保证 SQL 语法正确的前提。
2. 善用命名参数：AI.SIMILARITY全程使用=>命名参数风格，可读性强、不易错位，建议保持与官方示例一致。
3. 为NULL兜底：函数在出错时返回NULL，涉及后续过滤/排序时应显式处理空值。
4. 选择合适的端点：纯文本比较优先使用text-embedding-005一类文本嵌入端点；多模态场景参考multimodalembedding@001。端点的选择决定了向量表示质量。
5. 按需控制模型参数：通过model_params传入temperature、max_output_tokens等参数时，注意其为 JSON 字符串，需保证格式合法，且参数键须与端点模型能力匹配。
6. 认清函数分工：单对文本比较用AI.SIMILARITY；整表打分排序用AI.SCORE；大规模语义检索用AI.SEARCH，避免把表值搜索误用为标量调用。

九、相关资源

• Skill 定义与函数路由总表：bigquery-ai-ml/SKILL.md
• 本文主题参考文件：bigquery_ai_similarity.md
• 同族函数参考：AI.SCORE（bigquery_ai_score.md）、AI.SEARCH（bigquery_ai_search.md）
• Skill 加载实现：bigquery_skill.py
• SQL 执行工具集：bigquery_toolset.py
• 上层工具入口（含迁移提示）：bigquery_toolset.py

【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python