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
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
Tópicos
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_inferenceprocessador em coleções de pesquisa vetorial (tipoVECTORSEARCH) em um NextGen grupo de coleção. OpenSearch O Serverless aceita apenas modelos com umfunction_namedoremote. 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-groupemy-collectioncom seus próprios nomes.aws opensearchserverless create-collection-group \ --namemy-collection-group\ --generation NEXTGEN \ --standby-replicas ENABLED \ --capacity-limits maxIndexingCapacityInOCU=8,maxSearchCapacityInOCU=8aws opensearchserverless create-collection \ --namemy-collection\ --type VECTORSEARCH \ --collection-group-namemy-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.
-
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.comprincipal do serviço e a política de permissões da função devem permitirbedrock:InvokeModelno modelo. O principal que cria o conector também precisaiam:PassRolesobre esse papel. -
Crie o conector . Substituir
regioncom o Região da AWS do modelo Amazon Bedrock,account-idcom o seu AWS ID da conta ebedrock-rolecom 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_functiona configuração retorna a incorporação em$.inference_results[0].output[0].data, que é o caminho usado pelos exemplos neste tópico. -
Registre o modelo com o conector. Substituir
my-connector-idcom 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.
-
Implante o modelo. Substituir
my-model-idcom o ID do modelo da etapa anterior.POST /_plugins/_ml/models/my-model-id/_deploy -
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. 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.
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.
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:
-
Encontre os nomes dos parâmetros na
request_bodydo conector do modelo. Cada${parameters.espaço reservado é um nome que você pode usar como chave noname}input_map. -
Chame a API de previsão com um valor de amostra para cada parâmetro.
-
Leia a resposta de previsão e escreva o caminho JSON para o valor que você deseja manter.
-
Atualizar
model_id,input_map, eoutput_mapna calha. -
Execute o
_simulateAPI em um documento de amostra para confirmar se o campo de saída tem o valor esperado.
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
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.
POSTmy-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 }
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.
Usando ml_inference em um canal de pesquisa
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.
POSTmy-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.
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
erro. Tente fazer a solicitação novamente após uma breve espera.my-pipeline is not defined
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.
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:ExecuteMLResourceno modelo. Adicione ummodelregra 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
esem vez deaoss. -
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
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.my-pipeline is not defined
Para saber mais
Para obter mais informações sobre o ml_inference processador, veja o seguinte:
-
Para obter a referência do processador de pipeline de ingestão, consulte Processador de inferência de ML
na OpenSearch Documentação site. -
Para obter a referência do processador de solicitações de pesquisa, consulte Processador de solicitação de pesquisa de inferência de ML
na OpenSearch Documentação site. -
Para obter a referência do processador de resposta de pesquisa, consulte Processador de respostas de pesquisa de inferência de ML
na OpenSearch Documentação site. -
Para obter um exemplo prático de resumo de revisão e pesquisa semântica, consulte Introdução aos processadores de inferência de ML em OpenSearch: resumo da revisão e busca semântica
na OpenSearch blog.