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 能力被封装为一个预置 Skillbigquery-ai-ml。该 Skill 的核心设计原则是优先使用标准 SQL 中的AI.*函数通过execute_sql()执行而不是为 Forecasting、Anomaly Detection 等功能引入专用高层工具。AI.SIMILARITY正是这套AI.*函数家族中的一员与其并列的还有函数用途AI.FORECAST基于预训练 TimesFM 模型做时序预测AI.CLASSIFY将非结构化数据归类到预定义标签AI.DETECT_ANOMALIES基于 TimesFM 识别时序异常AI.GENERATE/AI.GENERATE_BOOL/AI.GENERATE_DOUBLE/AI.GENERATE_INT按提示生成文本、布尔值、浮点数、整数AI.IF评估一条自然语言布尔条件AI.SCORE按语义相关性为条目打分配合ORDER BY使用AI.SIMILARITY计算两个输入之间的余弦相似度AI.SEARCH在启用自动向量生成的表上做语义搜索表值函数值得注意的是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指定用于生成嵌入的模型端点参考文档给出的示例值为multimodalembedding001model_params以 JSON 字符串形式传递模型级参数如temperature、max_output_tokensconnection_id用于指定 BigQuery 连接供底层 LLM/嵌入模型访问使用。四、输入参数详解参数必填类型说明content1是String第一个文本内容。content2是String第二个文本内容用于与content1比较。connection_id否String供 LLM 使用的 BigQuery 连接 ID。endpoint否String模型端点例如multimodalembedding001。model_params否JSONJSON 对象形式的模型参数例如temperature、max_output_tokens。对关键参数的进一步说明content1/content2二者均为必填的字符串。调用时直接传入字面量、列引用或表达式均可函数内部会将其交由端点模型编码为向量后再计算余弦相似度。endpoint决定使用哪个嵌入/多模态模型。参考文档给出的示例为multimodalembedding001多模态嵌入端点在与本文同目录的 bigquery_ai_search.md 中还能看到使用text-embedding-005文本嵌入端点的示例。端点是否配置会直接影响向量表示的质量因此在做文本语义比较时应优先选用专门的文本嵌入端点。model_params以 JSON 字符串传递模型推理参数。参考文档明确给出的示例键包括temperature与max_output_tokens。实际可用键取决于所选端点的模型能力。connection_id用于指定 BigQuery 连接格式如my-project.us.my-connection。当端点模型需要外部凭据或位于特定项目/区域时使用对于通过预配置默认端点即可工作的场景可以省略。五、输出 Schema列名类型说明(标量结果)FLOAT64相似度得分如余弦相似度。出错时返回NULL。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_typeEUCLIDEAN / 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( namebigquery_agent, modelgemini-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集成时建议以迁移后的路径为准。八、最佳实践与注意事项先读参考文件再生成 SQLbigquery-ai-mlSkill 的机制要求 Agent 在调用AI.*函数前必须读取对应的references/*.md文件且只能使用精确路径不能猜测文件名。这是保证 SQL 语法正确的前提。善用命名参数AI.SIMILARITY全程使用命名参数风格可读性强、不易错位建议保持与官方示例一致。为NULL兜底函数在出错时返回NULL涉及后续过滤/排序时应显式处理空值。选择合适的端点纯文本比较优先使用text-embedding-005一类文本嵌入端点多模态场景参考multimodalembedding001。端点的选择决定了向量表示质量。按需控制模型参数通过model_params传入temperature、max_output_tokens等参数时注意其为 JSON 字符串需保证格式合法且参数键须与端点模型能力匹配。认清函数分工单对文本比较用AI.SIMILARITY整表打分排序用AI.SCORE大规模语义检索用AI.SEARCH避免把表值搜索误用为标量调用。九、相关资源Skill 定义与函数路由总表bigquery-ai-ml/SKILL.md本文主题参考文件bigquery_ai_similarity.md同族函数参考AI.SCOREbigquery_ai_score.md、AI.SEARCHbigquery_ai_search.mdSkill 加载实现bigquery_skill.pySQL 执行工具集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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ADK 中的 BigQuery AI.SIMILARITY：使用 SQL 计算文本余弦相似度的完整指南
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 能力被封装为一个预置 Skillbigquery-ai-ml。该 Skill 的核心设计原则是优先使用标准 SQL 中的AI.*函数通过execute_sql()执行而不是为 Forecasting、Anomaly Detection 等功能引入专用高层工具。AI.SIMILARITY正是这套AI.*函数家族中的一员与其并列的还有函数用途AI.FORECAST基于预训练 TimesFM 模型做时序预测AI.CLASSIFY将非结构化数据归类到预定义标签AI.DETECT_ANOMALIES基于 TimesFM 识别时序异常AI.GENERATE/AI.GENERATE_BOOL/AI.GENERATE_DOUBLE/AI.GENERATE_INT按提示生成文本、布尔值、浮点数、整数AI.IF评估一条自然语言布尔条件AI.SCORE按语义相关性为条目打分配合ORDER BY使用AI.SIMILARITY计算两个输入之间的余弦相似度AI.SEARCH在启用自动向量生成的表上做语义搜索表值函数值得注意的是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指定用于生成嵌入的模型端点参考文档给出的示例值为multimodalembedding001model_params以 JSON 字符串形式传递模型级参数如temperature、max_output_tokensconnection_id用于指定 BigQuery 连接供底层 LLM/嵌入模型访问使用。四、输入参数详解参数必填类型说明content1是String第一个文本内容。content2是String第二个文本内容用于与content1比较。connection_id否String供 LLM 使用的 BigQuery 连接 ID。endpoint否String模型端点例如multimodalembedding001。model_params否JSONJSON 对象形式的模型参数例如temperature、max_output_tokens。对关键参数的进一步说明content1/content2二者均为必填的字符串。调用时直接传入字面量、列引用或表达式均可函数内部会将其交由端点模型编码为向量后再计算余弦相似度。endpoint决定使用哪个嵌入/多模态模型。参考文档给出的示例为multimodalembedding001多模态嵌入端点在与本文同目录的 bigquery_ai_search.md 中还能看到使用text-embedding-005文本嵌入端点的示例。端点是否配置会直接影响向量表示的质量因此在做文本语义比较时应优先选用专门的文本嵌入端点。model_params以 JSON 字符串传递模型推理参数。参考文档明确给出的示例键包括temperature与max_output_tokens。实际可用键取决于所选端点的模型能力。connection_id用于指定 BigQuery 连接格式如my-project.us.my-connection。当端点模型需要外部凭据或位于特定项目/区域时使用对于通过预配置默认端点即可工作的场景可以省略。五、输出 Schema列名类型说明(标量结果)FLOAT64相似度得分如余弦相似度。出错时返回NULL。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_typeEUCLIDEAN / 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( namebigquery_agent, modelgemini-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集成时建议以迁移后的路径为准。八、最佳实践与注意事项先读参考文件再生成 SQLbigquery-ai-mlSkill 的机制要求 Agent 在调用AI.*函数前必须读取对应的references/*.md文件且只能使用精确路径不能猜测文件名。这是保证 SQL 语法正确的前提。善用命名参数AI.SIMILARITY全程使用命名参数风格可读性强、不易错位建议保持与官方示例一致。为NULL兜底函数在出错时返回NULL涉及后续过滤/排序时应显式处理空值。选择合适的端点纯文本比较优先使用text-embedding-005一类文本嵌入端点多模态场景参考multimodalembedding001。端点的选择决定了向量表示质量。按需控制模型参数通过model_params传入temperature、max_output_tokens等参数时注意其为 JSON 字符串需保证格式合法且参数键须与端点模型能力匹配。认清函数分工单对文本比较用AI.SIMILARITY整表打分排序用AI.SCORE大规模语义检索用AI.SEARCH避免把表值搜索误用为标量调用。九、相关资源Skill 定义与函数路由总表bigquery-ai-ml/SKILL.md本文主题参考文件bigquery_ai_similarity.md同族函数参考AI.SCOREbigquery_ai_score.md、AI.SEARCHbigquery_ai_search.mdSkill 加载实现bigquery_skill.pySQL 执行工具集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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考