View a markdown version of this page

Pipelines de inferência de ML na Amazon OpenSearch Sem servidor - Amazônia OpenSearch Serviço

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Pipelines de inferência de ML na Amazon OpenSearch Sem servidor

O ml_inference processador na Amazon OpenSearch Serverless é um processador de uso geral que chama um modelo de aprendizado de máquina configurado e mapeia as entradas e saídas do modelo para campos de documentos ou consultas. Você controla o mapeamento com o input_map e output_map parâmetros, que especificam os campos do documento ou da consulta que fornecem a entrada do modelo e os campos que recebem a saída do modelo.

Ao contrário dos processadores de aprendizado de máquina desenvolvidos especificamente, como text_embedding, text_image_embedding, e sparse_encoding, cada um dos quais suporta um único tipo de modelo, o ml_inference o processador funciona com qualquer modelo configurado. Ele também pode ser executado em pipelines de ingestão e pipelines de pesquisa, para que você possa aplicar a inferência do modelo durante a indexação, antes da execução de uma consulta ou depois que os resultados forem retornados. Use o ml_inference processador quando você precisa de um modelo ou de um mapeamento de entrada e saída que os processadores criados especificamente não fornecem. Para obter a documentação conceitual completa, consulte Processador de inferência de ML na OpenSearch Documentação site.

Você pode usar o ml_inference processador para suportar fluxos de trabalho como os seguintes:

  • Pesquisa semântica

  • Retrieval-augmented geração (RAG)

  • Pesquisa multimodal

  • Resumo dos resultados

  • Enriquecimento de consultas

Pré-requisitos

Antes de usar o ml_inference processador, complete o seguinte:

  • Crie uma coleção de pesquisa vetorial. OpenSearch O Serverless suporta o ml_inference processador em coleções de pesquisa vetorial (tipo VECTORSEARCH) em um NextGen grupo de coleção. OpenSearch O Serverless aceita apenas modelos com um function_name do remote. Para criar o grupo de coleções, consulte Crie um grupo de coleções. Para criar a coleção, consulte Trabalho com coleções de pesquisa vetorial. Habilite réplicas em espera no grupo de coleta e na coleção.

    O seguinte AWS CLI exemplo cria um NextGen grupo de coleções e uma coleção de busca vetorial nele. Substituir my-collection-group e my-collection com seus próprios nomes.

    aws opensearchserverless create-collection-group \ --name my-collection-group \ --generation NEXTGEN \ --standby-replicas ENABLED \ --capacity-limits maxIndexingCapacityInOCU=8,maxSearchCapacityInOCU=8 aws opensearchserverless create-collection \ --name my-collection \ --type VECTORSEARCH \ --collection-group-name my-collection-group \ --standby-replicas ENABLED
  • Configure e implante um modelo remoto. O processador chama um modelo remoto configurado e implantado, ao qual você faz referência pelo ID do modelo. Para ver um exemplo que configura um modelo de incorporação do Amazon Titan, consulte Exemplo: configurar um modelo de incorporação do Amazon Titan. Para obter mais informações, consulte Configurar o Machine Learning no Amazon OpenSearch Serverless.

  • Assine suas solicitações. Assine todas as solicitações no endpoint de coleta com AWS Assinatura versão 4 usando o nome do serviço aoss. Para obter mais informações, consulte Assinar solicitações HTTP com outros clientes.

Exemplo: configurar um modelo de incorporação do Amazon Titan

Os exemplos neste tópico usam um modelo Amazon Titan Text Embeddings V2 no Amazon Bedrock. As etapas a seguir criam o conector e o modelo em sua coleção.

  1. Crie uma função do IAM que OpenSearch Serverless presume ligar para Amazon Bedrock. A política de confiança da função deve permitir a ml.opensearchservice.amazonaws.com principal do serviço e a política de permissões da função devem permitir bedrock:InvokeModel no modelo. O principal que cria o conector também precisa iam:PassRole sobre esse papel.

  2. Crie o conector . Substituir region com o Região da AWS do modelo Amazon Bedrock, account-id com o seu AWS ID da conta e bedrock-role com o nome da função da etapa anterior.

    POST /_plugins/_ml/connectors/_create { "name": "Amazon Bedrock Titan Text Embeddings V2", "description": "Connector for amazon.titan-embed-text-v2:0", "version": 1, "protocol": "aws_sigv4", "parameters": { "region": "region", "service_name": "bedrock", "model": "amazon.titan-embed-text-v2:0" }, "credential": { "roleArn": "arn:aws:iam::account-id:role/bedrock-role" }, "actions": [ { "action_type": "predict", "method": "POST", "url": "https://bedrock-runtime.${parameters.region}.amazonaws.com/model/${parameters.model}/invoke", "headers": { "content-type": "application/json", "x-amz-content-sha256": "required" }, "request_body": "{ \"inputText\": \"${parameters.inputText}\" }", "post_process_function": "connector.post_process.bedrock.embedding" } ] }

    A resposta contém a ID do conector. O post_process_function a configuração retorna a incorporação em $.inference_results[0].output[0].data, que é o caminho usado pelos exemplos neste tópico.

  3. Registre o modelo com o conector. Substituir my-connector-id com a ID do conector da etapa anterior.

    POST /_plugins/_ml/models/_register { "name": "titan-embed-text-v2", "function_name": "remote", "description": "Amazon Titan Text Embeddings V2", "connector_id": "my-connector-id" }

    A resposta contém o ID do modelo.

  4. Implante o modelo. Substituir my-model-id com o ID do modelo da etapa anterior.

    POST /_plugins/_ml/models/my-model-id/_deploy
  5. Teste o modelo com a API de previsão, conforme mostrado em Combine o processador com seu modelo.

Essas etapas exigem as seguintes permissões no model tipo de recurso: aoss:CreateMLResource para criar o conector e registrar o modelo, aoss:UpdateMLResource para implantá-lo e aoss:ExecuteMLResource para chamar a API de previsão. Para ver um exemplo de política de acesso a dados que concede essas permissões, consulte Configurar permissões para Machine Learning.

Combine o processador com seu modelo

O ml_inference o processador não conhece a forma do seu modelo. Você conta isso com input_map e output_map. Se eles não corresponderem à API de previsão do modelo, o processador falhará ou gravará o valor errado. Teste o modelo com a API de previsão primeiro e depois copie os nomes dos parâmetros e o caminho de saída em seu pipeline.

A tabela a seguir mostra de onde vem cada parte do mapeamento.

Mapeamento O que deve corresponder
Introduza input_map Um nome de parâmetro na solicitação de previsão, que é ${parameters.name} espaço reservado no conector request_body.
Valor em input_map O campo do documento, ou o campo de consulta, que fornece o valor.
Introduza output_map O nome do campo que recebe a saída do modelo.
Valor em output_map Um caminho JSON para a resposta de previsão, por exemplo $.inference_results[0].output[0].data.

O exemplo a seguir chama a API de previsão para um modelo de incorporação de texto. O inputText parâmetro é o mesmo nome que o exemplo do pipeline de ingestão usa como chave em input_map. Substituir my-model-id com o ID do seu modelo implantado.

POST /_plugins/_ml/models/my-model-id/_predict { "parameters": { "inputText": "Example document text" } }

O modelo retorna uma resposta como a seguinte. O data a matriz é encurtada para facilitar a leitura.

{ "inference_results": [ { "output": [ { "name": "sentence_embedding", "data_type": "FLOAT32", "shape": [1024], "data": [0.0123, -0.0456, 0.0789] } ], "status_code": 200 } ] }

A incorporação está no data matriz da primeira saída. O caminho JSON $.inference_results[0].output[0].data seleciona isso. Esse é o caminho que o exemplo do pipeline de ingestão usa no output_map.

nota

Essa forma de resposta se aplica quando o conector de incorporação do Amazon Titan é definido post_process_function para connector.post_process.bedrock.embedding. Sem uma função de pós-processamento, o vetor está em $.inference_results[0].output[0].dataAsMap.embedding em vez disso. Para configuração do conector, consulte Configurar o Machine Learning no Amazon OpenSearch Serverless.

Importante

Os parâmetros da solicitação e a forma da resposta dependem do modelo e do conector. Ao usar um modelo diferente, não reutilize os caminhos dos exemplos neste tópico. Execute a API de previsão para seu modelo e leia os caminhos de sua resposta.

Por exemplo, um modelo de linguagem grande que retorna sua resposta bruta tem uma forma diferente. O texto está aninhado dentro do dataAsMap objeto, e o parâmetro que você envia tem o nome do espaço reservado do conector em vez de inputText.

POST /_plugins/_ml/models/my-llm-model-id/_predict { "parameters": { "messages": "[{\"role\":\"user\",\"content\":[{\"text\":\"Summarize: Example text\"}]}]" } }
{ "inference_results": [ { "output": [ { "name": "response", "dataAsMap": { "output": { "message": { "role": "assistant", "content": [ { "text": "A short summary of the example text." } ] } }, "stopReason": "end_turn" } } ], "status_code": 200 } ] }

Para essa resposta, o caminho JSON é $.inference_results[0].output[0].dataAsMap.output.message.content[0].text. A estrutura exata abaixo dataAsMap é a resposta do seu fornecedor de modelos, portanto, ela difere entre fornecedores e modelos.

Para mudar o processador para um modelo diferente, faça o seguinte:

  1. Encontre os nomes dos parâmetros na request_body do conector do modelo. Cada ${parameters.name} espaço reservado é um nome que você pode usar como chave no input_map.

  2. Chame a API de previsão com um valor de amostra para cada parâmetro.

  3. Leia a resposta de previsão e escreva o caminho JSON para o valor que você deseja manter.

  4. Atualizar model_id, input_map, e output_map na calha.

  5. Execute o _simulate API em um documento de amostra para confirmar se o campo de saída tem o valor esperado.

nota

A API de previsão exige o aoss:ExecuteMLResource permissão no recurso modelo. Para obter mais informações, consulte Configurar o Machine Learning no Amazon OpenSearch Serverless.

Usando ml_inference em um pipeline de ingestão

Em um pipeline de ingestão, o ml_inference o processador executa a inferência do modelo durante a indexação. Um uso comum é gerar incorporações vetoriais a partir de um campo de texto para que você possa executar uma pesquisa semântica em seus dados. O input_map mapeia um campo de documento para a entrada do modelo e o output_map grava a saída do modelo em um novo campo.

O exemplo a seguir cria um pipeline que envia o text campo no modelo e grava a incorporação retornada em um embedding campo. Substituir my-pipeline com o nome do seu funil e my-model-id com o ID do seu modelo implantado.

PUT _ingest/pipeline/my-pipeline { "description": "Generates embeddings with a configured model", "processors": [ { "ml_inference": { "model_id": "my-model-id", "full_response_path": true, "input_map": [ { "inputText": "text" } ], "output_map": [ { "embedding": "$.inference_results[0].output[0].data" } ] } } ] }

A solicitação retorna a seguinte resposta:

{ "acknowledged": true }

O output_map o caminho está enraizado em inference_results porque full_response_path está definido como true. Essa configuração avalia o caminho de saída em relação à resposta completa do modelo. Para obter mais informações, consulte Processador de inferência de ML na OpenSearch Documentação site.

Antes de aplicar o pipeline ao tráfego em tempo real, você pode simulá-lo em documentos de amostra com o _simulate ponto final. Para executar a inferência de modelo automaticamente em cada documento indexado em um índice, defina o index.default_pipeline configuração ao criar o índice. Como alternativa, especifique o pipeline em uma solicitação de indexação individual com o pipeline parâmetro de consulta. Para obter mais informações sobre como criar, simular e aplicar pipelines de ingestão, consulte Ingira pipelines na Amazon OpenSearch Sem servidor.

O exemplo a seguir indexa um documento e executa o pipeline. Substituir my-index com o nome do seu índice e my-pipeline com o nome do seu funil.

POST my-index/_doc?pipeline=my-pipeline { "text": "Example document text" }

A resposta confirma que o documento foi indexado:

{ "_index": "my-index", "_id": "93VTg6EBtHTIBjFym5yW", "_version": 1, "result": "created", "_shards": { "total": 0, "successful": 0, "failed": 0 }, "_seq_no": 0, "_primary_term": 0 }
nota

O índice alvo deve ser configurado para pesquisa vetorial. Habilitar index.knn e mapeie o campo de saída (por exemplo, embedding) como um knn_vector campo com uma dimensão que corresponde ao seu modelo.

Em um canal de busca, o ml_inference o processador executa a inferência do modelo como parte de uma consulta. Um processador de solicitação de pesquisa transforma ou regrava a consulta antes de executá-la. Um processador de respostas de pesquisa enriquece os resultados antes de você recebê-los. Para executar um canal de busca, envie a solicitação com o search_pipeline parâmetro de consulta. Substituir my-index com o nome do seu índice e my-pipeline com o nome do seu funil.

POST my-index/_search?search_pipeline=my-pipeline

Para criar ou atualizar um canal de pesquisa, envie o corpo do pipeline para o _search/pipeline endpoint, como mostram os exemplos nas seções a seguir.

nota

Um canal de pesquisa recém-criado pode levar alguns minutos para entrar em vigor, mesmo após o retorno da solicitação de criação "acknowledged": true. Até lá, as solicitações de pesquisa que fazem referência ao pipeline falham com um Pipeline my-pipeline is not defined erro. Tente fazer a solicitação novamente após uma breve espera.

Processador de solicitações de pesquisa

Você usa um processador de solicitação de pesquisa para reescrever uma consulta recebida antes OpenSearch O Serverless o executa. O exemplo a seguir usa o texto de um match consulta, gera um vetor a partir dela com um modelo configurado e reescreve a solicitação em uma consulta k-NN com o query_template parâmetro. OpenSearch O Serverless substitui o ${query_vec} espaço reservado no modelo com a saída do modelo que output_map capturas. Substituir my-model-id com o ID do seu modelo implantado.

PUT /_search/pipeline/my-pipeline { "request_processors": [ { "ml_inference": { "model_id": "my-model-id", "full_response_path": true, "query_template": "{\"size\":2,\"_source\":[\"text\"],\"query\":{\"knn\":{\"embedding\":{\"vector\":${query_vec},\"k\":2}}}}", "input_map": [ { "inputText": "query.match.text.query" } ], "output_map": [ { "query_vec": "$.inference_results[0].output[0].data" } ], "ignore_missing": true } } ] }

Conjunto full_response_path para true para que o output_map O caminho JSON é resolvido em relação à resposta completa do modelo. Isso permite que você use o mesmo caminho de saída que você leu na resposta da API de previsão.

Conjunto ignore_missing para true quando o campo de origem pode estar ausente. Uma consulta que não contém o campo mapeado, como um match_all consulta e, em seguida, passa inalterada em vez de falhar. O processador ainda reescreve as consultas que contêm o campo.

Processador de resposta de pesquisa

Um processador de resposta de pesquisa é executado após o retorno de uma consulta, para que você possa enriquecer ou resumir cada ocorrência. O exemplo a seguir envia o text campo de cada ocorrência em um modelo configurado e grava a saída do modelo em um text_vec campo. Conjunto one_to_one para true para que o processador execute o modelo uma vez para cada busca. O padrão é false, que envia todas as ocorrências para o modelo em uma única solicitação, e os modelos que esperam um único valor de entrada rejeitam essa solicitação. Substituir my-model-id com o ID do seu modelo implantado.

PUT /_search/pipeline/my-pipeline { "response_processors": [ { "ml_inference": { "model_id": "my-model-id", "full_response_path": true, "input_map": [ { "inputText": "text" } ], "output_map": [ { "text_vec": "$.inference_results[0].output[0].data" } ], "one_to_one": true } } ] }

Para resumir os resultados com um modelo de linguagem grande, adicione um model_config objeto que contém o prompt do modelo e definido one_to_one para true para que o processador resuma cada resultado da pesquisa separadamente. O prompt pode referenciar a entrada mapeada por meio de um parâmetro de modelo, como ${parameters.context}. O output_map o caminho neste exemplo corresponde a um modelo que retorna sua resposta bruta. Para obter mais informações, consulte Combine o processador com seu modelo. Substituir my-model-id com o ID do seu modelo implantado.

PUT /_search/pipeline/my-pipeline { "response_processors": [ { "ml_inference": { "model_id": "my-model-id", "full_response_path": true, "input_map": [ { "context": "text" } ], "output_map": [ { "summary": "$.inference_results[0].output[0].dataAsMap.output.message.content[0].text" } ], "model_config": { "messages": "[{\"role\":\"user\",\"content\":[{\"text\":\"Summarize the following text: ${parameters.context}\"}]}]" }, "one_to_one": true } } ] }

Preços

O ml_inference o processador é executado na computação que processa as solicitações da sua coleção. Em um pipeline de ingestão, seu processamento conta para a indexação OpenSearch Unidades de computação (OCUs) para sua coleção. Em um canal de pesquisa, seu processamento conta para os OCUs de pesquisa, da mesma forma que outras atividades de indexação e pesquisa. Pipelines com mais processadores ou com processadores de computação intensiva consomem mais capacidade do que pipelines simples. Para obter mais informações sobre como a capacidade é escalada e faturada, consulte Gerenciando limites de capacidade para a Amazon OpenSearch Sem servidor e Amazônia OpenSearch Preços do serviço.

O processador também invoca o modelo remoto que você configurou, e o fornecedor do modelo fatura a inferência do modelo separadamente.

Permissões obrigatórias

Gerenciando os pipelines de pesquisa e ingestão que contêm um ml_inference o processador mapeia para o seguinte OpenSearch Permissões da política de acesso a dados sem servidor. As permissões se aplicam ao collection tipo de recurso.

  • aoss:CreateCollectionItems — Crie ou atualize um funil.

  • aoss:DescribeCollectionItems — Obtenha, liste e simule pipelines.

  • aoss:DeleteCollectionItems — Exclua um funil.

O processador também chama o modelo que você configurou. Para obter as permissões de política de acesso a dados que um diretor precisa para criar e executar modelos, consulte Configurar o Machine Learning no Amazon OpenSearch Serverless.

Importante

O principal que envia uma solicitação pelo pipeline precisa do aoss:ExecuteMLResource permissão no modelo. Isso se aplica à indexação de documentos, execução _simulatee pesquisando. Sem essa permissão, essas solicitações falham com um Forbidden erro que não indica a permissão ausente.

O exemplo de política de acesso a dados a seguir concede uma permissão principal para gerenciar pipelines em uma coleção e executar os modelos nessa coleção. Substituir collection-name com o nome da sua coleção, account-id com o seu AWS ID da conta e role-name com o nome da função do IAM que gerencia e usa os pipelines.

[ { "Description": "Manage pipelines and run models", "Rules": [ { "ResourceType": "collection", "Resource": ["collection/collection-name"], "Permission": [ "aoss:CreateCollectionItems", "aoss:DescribeCollectionItems", "aoss:DeleteCollectionItems" ] }, { "ResourceType": "model", "Resource": ["model/collection-name/*"], "Permission": [ "aoss:ExecuteMLResource" ] } ], "Principal": [ "arn:aws:iam::account-id:role/role-name" ] } ]

Para o mapeamento completo de OpenSearch Operações de API para OpenSearch Permissões sem servidor, consulte Operações e plug-ins compatíveis no Amazon OpenSearch Serverless.

Solução de problemas

Se uma solicitação que usa um ml_inference o pipeline falha com um Forbidden erro, verifique as seguintes causas comuns:

  • O diretor chamador não tem aoss:ExecuteMLResource no modelo. Adicione um model regra para a política de acesso a dados, conforme mostrado em Permissões obrigatórias.

  • A política de acesso a dados não concede ao diretor as permissões de indexação ou coleta para a operação, como escrever documentos, pesquisar ou criar pipelines.

  • A solicitação é assinada com o nome do serviço es em vez de aoss.

  • A política de rede para a coleção não permite o acesso da origem da solicitação.

Se uma solicitação de pesquisa falhar com um Pipeline my-pipeline is not defined erro logo após criar o pipeline, aguarde alguns minutos e tente novamente. Para obter mais informações, consulte Usando ml_inference em um canal de pesquisa.

Para saber mais

Para obter mais informações sobre o ml_inference processador, veja o seguinte: