# 嵌入函数

注意

此功能从版本1.2.1开始可用。

EmbedText函数集成了来自各种提供商的嵌入API接口,如Amazon BedrockAmazon SageMakerCohereGeminiHuggingFaceJina AIOpenAIVoyage AI,简化了将文本转换为向量的过程。它支持高吞吐量的自动批处理,适用于实时搜索和批处理。

语法

EmbedText(text, provider, base_url, api_key, others)

参数

  • text (String): 要转换为向量的非空字符串。
  • provider (String): 嵌入模型提供商。必须是以下之一,不区分大小写:OpenAIHuggingFaceCohereVoyageAIBedrockSageMakerJinaGemini
  • base_url (String): 嵌入API的URL。对于某些提供商,此参数是可选的。
  • api_key (String): 嵌入提供商API密钥。
  • others (String): 提供商嵌入API请求的可选附加参数。它应该作为JSON映射提供,并可以包括:
    • batch_size:每个API请求中可以包含的文本的最大数量因所使用的嵌入模型而异。默认情况下,此大小根据特定模型的功能和限制进行设置。当EmbedText函数在批处理模式下运行时,它会在数据发送到嵌入API之前在函数内部自动将多个文本合并为一个批次。此聚合过程由函数在数据发送到嵌入API之前内部完成。
    • 其他特定于提供商的参数,详见各自的API文档。

返回值

  • 该函数返回从输入文本转换而来的向量。该向量是一个由Float32值组成的数组,表示所选提供商的嵌入API处理的文本的数值嵌入。
  • 类型:Array(Float32)

# Amazon Bedrock Embedding

EmbedText中将provider参数设置为Bedrock,将使用Amazon Bedrock Titan Embedding API (opens new window)进行文本嵌入。

提供商特定参数

  • base_url:此提供商不适用。
  • api_key:AWS secret_access_key。必填。
  • others
    • batch_size:此提供商不支持批处理嵌入,因此不相关。
    • model:要使用的模型ID。必填。
    • access_key_id:AWS access_key_id。必填。
    • region_name:AWS区域名称。必填。

示例

SELECT EmbedText('YOUR_TEXT', 'Bedrock', '', 'SECRET_ACCESS_KEY', '{"model":"amazon.titan-embed-text-v1", "region_name":"us-east-1", "access_key_id":"ACCESS_KEY_ID"}')

使用自定义函数简化用法:

CREATE FUNCTION BedrockEmbedText ON CLUSTER '{cluster}' AS (x) -> EmbedText(x, 'Bedrock', '', 'SECRET_ACCESS_KEY', '{"model":"amazon.titan-embed-text-v1", "region_name":"us-east-1", "access_key_id":"ACCESS_KEY_ID"}')
SELECT BedrockEmbedText('YOUR_TEXT')

# Amazon SageMaker Embedding

EmbedText中将provider参数设置为SageMaker,将使用Amazon SageMaker Endpoints (opens new window)进行文本嵌入。

注意:此提供商专门用于在Amazon SageMaker上部署的模型,具有特定的输入和输出格式要求。嵌入API的预期输入格式是一个JSON对象,其中“input_name”可以是单个文本或文本列表。API响应的结构为{"output_name": output},其中'output'是单个嵌入向量或嵌入向量列表,具体取决于输入是单个文本还是列表。

SageMaker JumpStart (opens new window)中很容易找到符合这些先决条件的模型。下图显示了此类模型的示例:

sagemaker-deploy

提供商特定参数

  • base_url:SageMaker Endpoint名称。必填。
  • api_key:AWS secret_access_key。必填。
  • others
    • batch_size:每个API请求中的文本最大数量。可选,默认值为50。如果不支持批处理嵌入,请将其设置为1。
    • access_key_id:AWS access_key_id。必填。
    • region_name:AWS区域名称。必填。
    • input_name:API输入名称。可选,默认值为'text_inputs'。
    • output_name:API输出名称。可选,默认值为'embedding'。
    • model_args:特定于使用的SageMaker端点的可选参数。

示例 使用默认值:

SELECT EmbedText('YOUR_TEXT', 'SageMaker', 'SAGEMAKER_ENDPOINT', 'SECRET_ACCESS_KEY', '{"region_name":"us-east-1", "access_key_id":"ACCESS_KEY_ID", "model_args":{"mode":"embedding"}}')

使用自定义值:

SELECT EmbedText('YOUR_TEXT', 'SageMaker', 'SAGEMAKER_ENDPOINT', 'SECRET_ACCESS_KEY', '{"region_name":"us-east-1", "access_key_id":"ACCESS_KEY_ID", "model_args":{"mode":"embedding"}, "input_name":"inputs", "output_name":"embedding"}')

使用自定义函数简化用法:

CREATE FUNCTION SageMakerEmbedText ON CLUSTER '{cluster}' AS (x)-> EmbedText(x, 'SageMaker', 'SAGEMAKER_ENDPOINT', 'SECRET_ACCESS_KEY', '{"region_name":"us-east-1", "access_key_id":"ACCESS_KEY_ID", "model_args":{"mode":"embedding"}}')
SELECT SageMakerEmbedText('YOUR_TEXT')

# Cohere Embedding

EmbedText中将provider参数设置为Cohere,将使用Cohere Embedding API (opens new window)进行文本嵌入。

提供商特定参数

  • base_url:Cohere Embedding API URL。可选,默认值为https://api.cohere.ai/v1/embed (opens new window)
  • api_key:Cohere API密钥。必填。
  • others
    • batch_size:每个API请求中的文本最大数量。可选,默认值为50。
    • model:要使用的模型ID。可选,默认值为embed-english-v2.0
    • input_type:输入文本的类型。可选。
    • truncate:可选。NONE|START|END之一,用于指定API如何处理超过最大标记长度的输入。

示例

使用默认值:

SELECT EmbedText('YOUR_TEXT', 'Cohere', '', 'COHERE_API_KEY', '')

使用自定义值:

SELECT EmbedText('YOUR_TEXT', 'Cohere', 'YOUR_EMBEDDING_API_URL', 'COHERE_API_KEY', '{"model":"YOUR_MODEL_ID", "batch_size":YOUR_BATCH_SIZE, "input_type":"search_query", "truncate":"END"}')

使用自定义函数简化用法:

CREATE FUNCTION CohereEmbedText ON CLUSTER '{cluster}' AS (x) -> EmbedText(x, 'Cohere', '', 'COHERE_API_KEY', '')
SELECT CohereEmbedText('YOUR_TEXT')

# Gemini Embedding

EmbedText中将provider参数设置为Gemini,将使用Gemini Embedding API (opens new window)进行文本嵌入。

提供商特定参数

  • base_url:Gemini Embedding API URL。可选,默认值为https://generativelanguage.googleapis.com/v1beta (opens new window)
  • api_key:Gemini API密钥。必填。
  • others
    • batch_size:每个API请求中的文本最大数量。可选,默认值为50。
    • model:要使用的模型ID。可选,默认值为models/embedding-001

示例

使用默认值:

SELECT EmbedText('YOUR_TEXT', 'Gemini', '', 'GEMINI_API_KEY', '')

使用自定义值:

SELECT EmbedText('YOUR_TEXT', 'Gemini', 'YOUR_EMBEDDING_API_URL', 'GEMINI_API_KEY', '{"model":"YOUR_MODEL_ID", "batch_size":YOUR_BATCH_SIZE}')

使用自定义函数简化用法:

CREATE FUNCTION GeminiEmbedText ON CLUSTER '{cluster}' AS (x) -> EmbedText(x, 'Gemini', '', 'GEMINI_API_KEY', '')
SELECT GeminiEmbedText('YOUR_TEXT')

# HuggingFace Embedding

EmbedText中将provider参数设置为HuggingFace,将使用HuggingFace Inference API/Inference Endpoint (opens new window)进行文本嵌入。

注意:它特别与遵循特定输入和输出格式的API兼容,如BAAI/BGE embedding (opens new window) API。嵌入API的预期输入是一个JSON对象,其中“inputs”可以是单个文本或文本列表。此API的响应将是一个嵌入向量或嵌入向量列表,具体取决于提供的输入。如果不支持批处理嵌入,则需要在others参数中将batch_size设置为1。

提供商特定参数

  • base_url:HuggingFace Embedding API URL。必填。
  • api_key:HuggingFace API密钥。必填。
  • others
    • batch_size:每个API请求中的文本最大数量。可选,默认值为32。
    • model_args:特定于使用的HuggingFace模型的可选参数。

示例

使用默认值:

SELECT EmbedText('YOUR_TEXT', 'HuggingFace', 'API_URL', 'HUGGINGFACE_API_KEY', '')

使用自定义值:

SELECT EmbedText('YOUR_TEXT', 'HuggingFace', 'API_URL', 'HUGGINGFACE_API_KEY', '{"model_args":{"parameters": {"truncation":true}}}')

使用自定义函数简化用法:

CREATE FUNCTION HuggingFaceEmbedText ON CLUSTER '{cluster}' AS (x) -> EmbedText(x, 'HuggingFace', 'API_URL', 'HUGGINGFACE_API_KEY', '')
SELECT HuggingFaceEmbedText('YOUR_TEXT')

# Jina AI Embedding

EmbedText中将provider参数设置为Jina,将使用Jina AI Embedding API (opens new window)进行文本嵌入。

  • base_url:Jina AI Embedding API URL。可选,默认值为https://api.jina.ai/v1/embeddings (opens new window)
  • api_key:Jina AI API密钥。必填。
  • others
    • batch_size:每个API请求中的文本最大数量。可选,默认值为50。
    • model:要使用的模型ID。可选,默认值为jina-embeddings-v2-base-en

示例

使用默认值:

SELECT EmbedText('YOUR_TEXT', 'Jina', '', 'JINAAI_API_KEY', '')

使用自定义值:

SELECT EmbedText('YOUR_TEXT', 'Jina', 'YOUR_EMBEDDING_API_URL', 'JINAAI_API_KEY', '{"model":"YOUR_MODEL_ID", "batch_size":YOUR_BATCH_SIZE}')

使用自定义函数简化用法:

CREATE FUNCTION JinaAIEmbedText ON CLUSTER '{cluster}' AS (x) -> EmbedText(x, 'Jina', '', 'JINAAI_API_KEY', '')
SELECT JinaAIEmbedText('YOUR_TEXT')

# OpenAI Embedding

EmbedText中将provider参数设置为OpenAI,将使用OpenAI Embedding API (opens new window)进行文本嵌入。

提供商特定参数

  • base_url:OpenAI Embedding API URL。可选,默认值为https://api.openai.com/v1/embeddings (opens new window)
  • api_key:OpenAI API密钥。必填。
  • others
    • batch_size:每个API请求中的文本最大数量。可选,默认值为50。
    • model:要使用的模型ID。可选,支持的模型包括 text-embedding-ada-002text-embedding-3-smalltext-embedding-3-large。默认值为 text-embedding-ada-002(适用于1.3.0版本之前),自1.3.0版本起,默认值更改为 text-embedding-3-small
    • dimensions: 结果输出嵌入应有的维度数。这是一个可选项,自1.3.0版本起提供。
    • user:用于您的最终用户的可选唯一标识符,帮助OpenAI进行监控和滥用检测。

示例

使用默认值:

SELECT EmbedText('YOUR_TEXT', 'OpenAI', '', 'OPENAI_API_KEY', '')

使用自定义值:

SELECT EmbedText('YOUR_TEXT', 'OpenAI', 'YOUR_EMBEDDING_API_URL', 'OPENAI_API_KEY', '{"model":"YOUR_MODEL_ID", "batch_size":YOUR_BATCH_SIZE, "user":"YOUR_USER_ID"}')

使用自定义函数简化用法:

CREATE FUNCTION OpenAIEmbedText ON CLUSTER '{cluster}' AS (x) -> EmbedText(x, 'OpenAI', '', 'OPENAI_API_KEY', '')
SELECT OpenAIEmbedText('YOUR_TEXT')

# Voyage AI Embedding

提供商特定参数

EmbedText中将provider参数设置为VoyageAI,将使用Voyage AI Embedding API (opens new window)进行文本嵌入。

  • base_url:Voyage AI Embedding API URL。可选,默认值为https://api.voyageai.com/v1/embeddings (opens new window)
  • api_key:Voyage AI API密钥。必填。
  • others
    • batch_size:每个API请求中的文本最大数量。可选,默认值为8。
    • model:要使用的模型ID。可选,默认为voyage-01

示例

使用默认值:

SELECT EmbedText('YOUR_TEXT', 'VoyageAI', '', 'VOYAGEAI_API_KEY', '')

使用自定义值:

SELECT EmbedText('YOUR_TEXT', 'VoyageAI', 'YOUR_EMBEDDING_API_URL', 'VOYAGEAI_API_KEY', '{"model":"YOUR_MODEL_ID", "batch_size":YOUR_BATCH_SIZE}')

使用自定义函数简化用法:

CREATE FUNCTION VoyageAIEmbedText ON CLUSTER '{cluster}' AS (x) -> EmbedText(x, 'VoyageAI', '', 'VOYAGEAI_API_KEY', '')
SELECT VoyageAIEmbedText('YOUR_TEXT')