Compartilhar via

ai_embed_text plugin (visualização)

  • Artigo

Aplica-se a: ✅Azure Data Explorer

O ai_embed_text plug-in permite a incorporação de texto usando modelos de linguagem, permitindo vários cenários relacionados à IA, como aplicativos de Geração Aumentada de Recuperação (RAG) e pesquisa semântica. O plug-in dá suporte a modelos de inserção do Serviço OpenAI do Azure acessados usando a identidade gerenciada.

Pré-requisitos

Sintaxe

evaluateai_embed_text (texto, connectionString [, opções [, IncludeErrorMessages]])

Saiba mais sobre as convenções de sintaxe.

Parâmetros

Nome Digitar Obrigatória Descrição
text string ✔️ O texto a ser incorporado. O valor pode ser uma referência de coluna ou um escalar constante.
connectionString string ✔️ A cadeia de conexão para o modelo de linguagem no formato <ModelDeploymentUri>;<AuthenticationMethod>; substitua <ModelDeploymentUri> e <AuthenticationMethod> pelo URI de implantação do modelo de IA e pelo método de autenticação, respectivamente.
options dynamic As opções que controlam chamadas para o ponto de extremidade do modelo de inserção. Consulte Opções.
IncludeErrorMessages bool Indica se os erros devem ser gerados em uma nova coluna na tabela de saída. Valor padrão: false.

Opções

A tabela a seguir descreve as opções que controlam a maneira como as solicitações são feitas para o ponto de extremidade do modelo de inserção.

Nome Tipo Descrição
RecordsPerRequest int Especifica o número de registros a serem processados por solicitação. Valor padrão: 1.
CharsPerRequest int Especifica o número máximo de caracteres a serem processados por solicitação. Valor padrão: 0 (ilimitado). O OpenAI do Azure conta tokens, com cada token sendo convertido aproximadamente em quatro caracteres.
RetriesOnThrottling int Especifica o número de tentativas de repetição quando ocorre limitação. Valor padrão: 0.
GlobalTimeout timespan Especifica o tempo máximo de espera por uma resposta do modelo de inserção. Valor padrão: null
ModelParameters dynamic Parâmetros específicos do modelo de inserção, como dimensões de incorporação ou identificadores de usuário para fins de monitoramento. Valor padrão: null.
ReturnSuccessfulOnly bool Indica se os itens processados com êxito devem ser retornados. Valor padrão: false. Se o parâmetro IncludeErrorMessages estiver definido como true, essa opção será sempre definida como false.

Configurar políticas de texto explicativo e identidade gerenciada

Para usar o ai_embed_text plug-in, você deve configurar as seguintes políticas:

  • identidade gerenciada: permita que a identidade gerenciada atribuída pelo sistema seja autenticada nos serviços OpenAI do Azure.
  • callout: autorize o domínio do endpoint do modelo de IA.

Para configurar essas políticas, use os comandos nas seguintes etapas:

  1. Configure a identidade gerenciada:

    .alter-merge cluster policy managed_identity
```
[
  {
    "ObjectId": "system",
    "AllowedUsages": "AzureAI"
  }
]
```

  2. Configure a política de texto explicativo:

    .alter-merge cluster policy callout
```
[
    {
        "CalloutType": "azure_openai",
        "CalloutUriRegex": "https://[A-Za-z0-9\\-]{3,63}\\.openai\\.azure\\.com/.*",
        "CanCall": true
    }
]
```

Devoluções

Retorna as seguintes novas colunas de inserção:

  • Uma coluna com o sufixo _embedding que contém os valores de inserção
  • Se configurada para retornar erros, uma coluna com o sufixo _embedding_error , que contém cadeias de caracteres de erro ou é deixada em branco se a operação for bem-sucedida.

Dependendo do tipo de entrada, o plug-in retorna resultados diferentes:

  • Referência de coluna: retorna um ou mais registros com colunas adicionais prefixadas pelo nome da coluna de referência. Por exemplo, se a coluna de entrada for chamada de TextData, as colunas de saída serão nomeadas TextData_embedding e, se configuradas para retornar erros, TextData_embedding_error.
  • Escalar constante: retorna um único registro com colunas adicionais que não são prefixadas. Os nomes das colunas são _embedding e, se configurados para retornar erros, _embedding_error.

Exemplos

O exemplo a seguir insere o texto Embed this text using AI usando o modelo de inserção do OpenAI do Azure.

let expression = 'Embed this text using AI';
let connectionString = 'https://myaccount.openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-06-01;managed_identity=system';
evaluate ai_embed_text(expression, connectionString)

O exemplo a seguir insere vários textos usando o modelo de inserção do OpenAI do Azure.

let connectionString = 'https://myaccount.openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-06-01;managed_identity=system';
let options = dynamic({
    "RecordsPerRequest": 10,
    "CharsPerRequest": 10000,
    "RetriesOnThrottling": 1,
    "GlobalTimeout": 2m
});
datatable(TextData: string)
[
    "First text to embed",
    "Second text to embed",
    "Third text to embed"
]
| evaluate ai_embed_text(TextData, connectionString, options , true)

Práticas recomendadas

Os modelos de inserção do OpenAI do Azure estão sujeitos a limitações pesadas e chamadas frequentes para esse plug-in podem atingir rapidamente os limites de limitação.

Para usar o plug-in com eficiência e minimizar a ai_embed_text limitação e os custos, siga estas práticas recomendadas:

  • Tamanho da solicitação de controle: ajuste o número de registros (RecordsPerRequest) e caracteres por solicitação (CharsPerRequest).
  • Controlar o tempo limite da consulta: defina GlobalTimeout como um valor menor que o tempo limite da consulta para garantir que o progresso não seja perdido em chamadas bem-sucedidas até esse ponto.
  • Manipular limites de taxa com mais facilidade: defina novas tentativas na limitação (RetriesOnThrottling).

Conteúdo relacionado