View a markdown version of this page

Amazon OpenSearch Serverless의 ML 추론 파이프라인 - Amazon OpenSearch Service

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

Amazon OpenSearch Serverless의 ML 추론 파이프라인

Amazon OpenSearch Serverless의 ml_inference 프로세서는 구성된 기계 학습 모델을 호출하고 모델의 입력 및 출력을 문서 또는 쿼리 필드에 매핑하는 범용 프로세서입니다. 모델 입력을 제공하는 문서 또는 쿼리 필드와 모델 출력을 수신하는 필드를 지정하는 input_map 및 output_map 파라미터로 매핑을 제어합니다.

sparse_encoding각각 단일 모델 유형을 지원하는 text_embedding, text_image_embedding및와 같이 특별히 구축된 기계 학습 프로세서와 달리 ml_inference 프로세서는 구성된 모든 모델과 함께 작동합니다. 또한 수집 파이프라인과 검색 파이프라인 모두에서 실행할 수 있으므로 인덱싱 중, 쿼리 실행 전 또는 결과가 반환된 후 모델 추론을 적용할 수 있습니다. 특별히 구축된 ml_inference 프로세서가 제공하지 않는 모델 또는 입력 및 출력 매핑이 필요한 경우 프로세서를 사용합니다. 전체 개념 문서는 OpenSearch 설명서 웹 사이트의 ML 추론 프로세서를 참조하세요.

ml_inference 프로세서를 사용하여 다음과 같은 워크플로를 지원할 수 있습니다.

  • 시맨틱 검색

  • 검색 증강 생성(RAG)

  • 다중 모달 검색

  • 결과 요약

  • 쿼리 보강

사전 조건

ml_inference 프로세서를 사용하기 전에 다음을 완료하세요.

  • 벡터 검색 컬렉션을 생성합니다. OpenSearch Serverless는 NextGen 컬렉션 그룹의 벡터 검색 컬렉션(유형 VECTORSEARCH)에서 ml_inference 프로세서를 지원합니다. OpenSearch Serverless는 function_name가 인 모델만 허용합니다remote. 컬렉션 그룹을 생성하려면 섹션을 참조하세요컬렉션 그룹 생성. 컬렉션을 생성하려면 섹션을 참조하세요벡터 검색 컬렉션 작업. 컬렉션 그룹과 컬렉션 모두에서 대기 복제본을 활성화합니다.

    다음 AWS CLI 예제에서는 NextGen 컬렉션 그룹과 벡터 검색 컬렉션을 생성합니다. my-collection-group 및 my-collection을 고유한 이름으로 바꿉니다.

    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
  • 원격 모델을 구성하고 배포합니다. 프로세서는 구성 및 배포된 원격 모델을 호출합니다.이 원격 모델은 모델 ID로 참조합니다. Amazon Titan 임베딩 모델을 설정하는 예제는 섹션을 참조하세요예: Amazon Titan 임베딩 모델 설정. 자세한 내용은 Amazon OpenSearch Serverless의 기계 학습 구성 섹션을 참조하세요.

  • 요청에 서명합니다. 서비스 이름를 사용하여 AWS 서명 버전 4를 사용하여 컬렉션 엔드포인트에 대한 모든 요청에 서명합니다aoss. 자세한 내용은 다른 클라이언트로 HTTP 요청 서명 섹션을 참조하세요.

예: Amazon Titan 임베딩 모델 설정

이 주제의 예제에서는 Amazon Bedrock의 Amazon Titan Text Embeddings V2 모델을 사용합니다. 다음 단계에서는 컬렉션에 커넥터와 모델을 생성합니다.

  1. OpenSearch Serverless가 Amazon Bedrock을 호출하기 위해 수임하는 IAM 역할을 생성합니다. 역할의 신뢰 정책은 ml.opensearchservice.amazonaws.com 서비스 보안 주체를 허용해야 하며 역할의 권한 정책은 모델에 bedrock:InvokeModel 대해를 허용해야 합니다. 커넥터를 생성하는 보안 주체도이 역할에 iam:PassRole 필요합니다.

  2. 커넥터를 생성하세요. region AWS 리전 을 Amazon Bedrock 모델의 로 바꾸고, account-id를 AWS 계정 ID로 바꾸고, bedrock-role을 이전 단계의 역할 이름으로 바꿉니다.

    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" } ] }

    응답에는 커넥터 ID가 포함됩니다. post_process_function 설정은이 주제의 예제에서 사용하는 경로$.inference_results[0].output[0].data인에 임베딩을 반환합니다.

  3. 커넥터를 사용하여 모델을 등록합니다. my-connector-id를 이전 단계의 커넥터 ID로 바꿉니다.

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

    응답에는 모델 ID가 포함됩니다.

  4. 모델을 배포합니다. my-model-id를 이전 단계의 모델 ID로 바꿉니다.

    POST /_plugins/_ml/models/my-model-id/_deploy
  5. 에 표시된 대로 예측 API를 사용하여 모델을 테스트합니다프로세서를 모델에 일치시킵니다..

이러한 단계에는 model 리소스 유형에 대한 다음 권한이 필요합니다. aoss:CreateMLResource는 커넥터를 생성하고 모델을 등록하며,는 모델을 aoss:UpdateMLResource 배포하고,는 예측 API를 호출aoss:ExecuteMLResource합니다. 이러한 권한을 부여하는 데이터 액세스 정책의 예는 섹션을 참조하세요기계 학습에 대한 권한 구성.

프로세서를 모델에 일치시킵니다.

ml_inference 프로세서는 모델의 모양을 알지 못합니다. input_map 및를 사용하여 알려줍니다output_map. 이러한 값이 모델의 예측 API와 일치하지 않으면 프로세서가 실패하거나 잘못된 값을 씁니다. 먼저 예측 API로 모델을 테스트한 다음 파라미터 이름과 출력 경로를 파이프라인에 복사합니다.

다음 표는 매핑의 각 부분이 어디에서 왔는지 보여줍니다.

매핑 일치 항목
의 키 input_map 커넥터의 ${parameters.name} 자리 표시자인 예측 요청의 파라미터 이름입니다request_body.
의 값 input_map 값을 제공하는 문서 필드 또는 쿼리 필드입니다.
의 키 output_map 모델 출력을 수신하는 필드의 이름입니다.
의 값 output_map 와 같은 예측 응답의 JSON 경로입니다$.inference_results[0].output[0].data.

다음 예제에서는 텍스트 임베딩 모델의 예측 API를 호출합니다. inputText 파라미터는 수집 파이프라인 예제에서의 키로 사용하는 것과 동일한 이름입니다input_map. my-model-id를 배포된 모델의 ID로 바꿉니다.

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

모델은 다음과 같은 응답을 반환합니다. 가독성을 위해 data 배열이 단축됩니다.

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

임베딩은 첫 번째 출력의 data 배열에 있습니다. JSON 경로가 이를 $.inference_results[0].output[0].data 선택합니다. 이는 수집 파이프라인 예제가에서 사용하는 경로입니다output_map.

참고

이 응답 셰이프는 Amazon Titan 임베딩 커넥터가 post_process_function로 설정된 경우에 적용됩니다connector.post_process.bedrock.embedding. 사후 처리 함수가 없으면 벡터가 $.inference_results[0].output[0].dataAsMap.embedding 대신에 있습니다. 커넥터 설정은 섹션을 참조하세요Amazon OpenSearch Serverless의 기계 학습 구성.

중요

요청 파라미터와 응답 셰이프는 모델과 해당 커넥터에 따라 달라집니다. 다른 모델을 사용하는 경우이 주제의 예제에서 경로를 재사용하지 마십시오. 모델의 예측 API를 실행하고 응답에서 경로를 읽습니다.

예를 들어 원시 응답을 반환하는 대규모 언어 모델은 모양이 다릅니다. 텍스트는 dataAsMap 객체 내부에 중첩되며 전송하는 파라미터는 대신 커넥터 자리 표시자의 이름을 따서 명명됩니다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 } ] }

이 응답의 경우 JSON 경로는 입니다$.inference_results[0].output[0].dataAsMap.output.message.content[0].text. 의 정확한 구조dataAsMap는 모델 공급자의 응답이므로 공급자와 모델 간에 다릅니다.

프로세서를 다른 모델로 전환하려면 다음을 수행합니다.

  1. request_body 모델 커넥터의에서 파라미터 이름을 찾습니다. 각 ${parameters.name} 자리 표시자는에서 키로 사용할 수 있는 이름입니다input_map.

  2. 각 파라미터에 대한 샘플 값을 사용하여 예측 API를 호출합니다.

  3. 예측 응답을 읽고 유지하려는 값에 JSON 경로를 씁니다.

  4. 파이프라인output_map에서 input_map, 및 model_id를 업데이트합니다.

  5. 샘플 문서에서 _simulate API를 실행하여 출력 필드에 예상한 값이 있는지 확인합니다.

참고

예측 API에는 모델 리소스에 대한 aoss:ExecuteMLResource 권한이 필요합니다. 자세한 내용은 Amazon OpenSearch Serverless의 기계 학습 구성 섹션을 참조하세요.

수집 파이프라인에서 ml_inference 사용

수집 파이프라인에서 ml_inference 프로세서는 인덱싱 중에 모델 추론을 실행합니다. 일반적인 용도는 텍스트 필드에서 벡터 임베딩을 생성하여 데이터에 대한 의미 체계 검색을 실행하는 것입니다. 는 문서 필드를 모델 입력에 input_map 매핑하고 모델 출력을 새 필드에 output_map씁니다.

다음 예제에서는 text 필드를 모델로 보내고 반환된 임베딩을 embedding 필드에 쓰는 파이프라인을 생성합니다. my-pipeline을 파이프라인 이름으로 바꾸고 my-model-id를 배포된 모델의 ID로 바꿉니다.

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" } ] } } ] }

요청은 다음 응답을 반환합니다.

{ "acknowledged": true }

가 로 설정되어 inference_results 있기 때문에 output_map 경로는에 루트가 지정full_response_path됩니다true. 이 설정은 전체 모델 응답과 비교하여 출력 경로를 평가합니다. 자세한 내용은 OpenSearch 설명서 웹 사이트의 ML 추론 프로세서를 참조하세요.

라이브 트래픽에 파이프라인을 적용하기 전에 _simulate 엔드포인트가 있는 샘플 문서에 대해 파이프라인을 시뮬레이션할 수 있습니다. 인덱스로 인덱싱된 모든 문서에서 모델 추론을 자동으로 실행하려면 인덱스를 생성할 때 index.default_pipeline 설정을 지정합니다. 또는 pipeline 쿼리 파라미터를 사용하여 개별 인덱싱 요청에 파이프라인을 지정합니다. 수집 파이프라인 생성, 시뮬레이션 및 적용에 대한 자세한 내용은 섹션을 참조하세요Amazon OpenSearch Serverless에서 파이프라인 수집.

다음 예시에서는 문서를 인덱싱하고 파이프라인을 실행합니다. my-index를 인덱스 이름으로 바꾸고 my-pipeline을 파이프라인 이름으로 바꿉니다.

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

응답은 문서가 인덱싱되었음을 확인합니다.

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

벡터 검색을 위해 대상 인덱스를 구성해야 합니다. 출력 필드(예: embedding)를 활성화index.knn하고 모델과 일치하는 차원이 있는 knn_vector 필드로 매핑합니다.

검색 파이프라인에서 ml_inference 프로세서는 쿼리의 일부로 모델 추론을 실행합니다. 검색 요청 프로세서는 실행되기 전에 쿼리를 변환하거나 다시 작성합니다. 검색 응답 프로세서는 결과를 받기 전에 결과를 보강합니다. 검색 파이프라인을 실행하려면 search_pipeline 쿼리 파라미터와 함께 요청을 전송합니다. my-index를 인덱스 이름으로 바꾸고 my-pipeline을 파이프라인 이름으로 바꿉니다.

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

검색 파이프라인을 생성하거나 업데이트하려면 다음 섹션의 예제와 같이 파이프라인 본문을 _search/pipeline 엔드포인트로 전송합니다.

참고

새로 생성된 검색 파이프라인은 생성 요청이를 반환한 후에도 적용되는 데 몇 분 정도 걸릴 수 있습니다"acknowledged": true. 그때까지 파이프라인을 참조하는 검색 요청은 Pipeline my-pipeline is not defined 오류와 함께 실패합니다. 잠시 기다린 후 요청을 다시 시도합니다.

검색 요청 프로세서

OpenSearch Serverless가 실행하기 전에 검색 요청 프로세서를 사용하여 수신 쿼리를 다시 작성합니다. 다음 예제에서는 match 쿼리의 텍스트를 가져와 구성된 모델로 벡터를 생성하고 query_template 파라미터를 사용하여 요청을 k-NN 쿼리에 다시 씁니다. OpenSearch Serverless는 템플릿의 ${query_vec} 자리 표시자를 output_map 캡처하는 모델 출력으로 바꿉니다. my-model-id를 배포된 모델의 ID로 바꿉니다.

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 } } ] }

output_map JSON 경로가 전체 모델 응답에 대해 확인true되도록를 full_response_path로 설정합니다. 이렇게 하면 예측 API 응답에서 읽은 것과 동일한 출력 경로를 사용할 수 있습니다.

소스 필드가 누락되었을 true 때 ignore_missing로 설정합니다. 쿼리와 같이 매핑된 필드가 포함되지 않은 match_all 쿼리는 실패하는 대신 변경되지 않고를 통과합니다. 프로세서는 여전히 필드가 포함된 쿼리를 다시 작성합니다.

검색 응답 프로세서

검색 응답 프로세서는 쿼리가 반환된 후 실행되므로 각 적중을 보강하거나 요약할 수 있습니다. 다음 예제에서는 각 적중의 text 필드를 구성된 모델에 보내고 모델 출력을 text_vec 필드에 씁니다. 프로세서가 각 검색 적중에 대해 모델을 한 번 실행true하도록 one_to_one 로 설정합니다. 기본값은 단일 요청으로 모든 적중을 모델에 false보내고 단일 입력 값이 예상되는 모델은 해당 요청을 거부하는 입니다. my-model-id를 배포된 모델의 ID로 바꿉니다.

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 } } ] }

대규모 언어 모델로 결과를 요약하려면 모델 프롬프트가 포함된 model_config 객체를 추가하고 프로세서가 각 검색 적중을 개별적으로 요약true하도록를 one_to_one로 설정합니다. 프롬프트는와 같은 템플릿 파라미터를 통해 매핑된 입력을 참조할 수 있습니다${parameters.context}. 이 예제의 output_map 경로는 원시 응답을 반환하는 모델과 일치합니다. 자세한 내용은 프로세서를 모델에 일치시킵니다. 섹션을 참조하세요. my-model-id를 배포된 모델의 ID로 바꿉니다.

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 } } ] }

요금

ml_inference 프로세서는 컬렉션의 요청을 처리하는 컴퓨팅에서 실행됩니다. 수집 파이프라인에서 처리는 컬렉션의 OpenSearch 컴퓨팅 유닛(OCUs) 인덱싱에 포함됩니다. 검색 파이프라인에서 처리는 다른 인덱싱 및 검색 OCUs에 포함됩니다. 프로세서가 많거나 컴퓨팅 집약적인 프로세서가 있는 파이프라인은 단순한 파이프라인보다 더 많은 용량을 소비합니다. 용량 확장 및 청구 방법에 대한 자세한 내용은 Amazon OpenSearch Serverless의 용량 제한 관리 및 Amazon OpenSearch Service 요금을 참조하세요.

또한 프로세서는 구성한 원격 모델을 호출하고 모델 공급자는 모델 추론을 별도로 청구합니다.

필수 권한

ml_inference 프로세서가 포함된 검색 및 수집 파이프라인을 관리하면 다음 OpenSearch Serverless 데이터 액세스 정책 권한에 매핑됩니다. 권한은 collection 리소스 유형에 적용됩니다.

  • aoss:CreateCollectionItems - 파이프라인을 생성하거나 업데이트합니다.

  • aoss:DescribeCollectionItems - 파이프라인을 가져오고, 나열하고, 시뮬레이션합니다.

  • aoss:DeleteCollectionItems - 파이프라인을 삭제합니다.

프로세서는 구성한 모델도 호출합니다. 보안 주체가 모델을 생성하고 실행하는 데 필요한 데이터 액세스 정책 권한은 섹션을 참조하세요Amazon OpenSearch Serverless의 기계 학습 구성.

중요

파이프라인을 통해 요청을 보내는 보안 주체는 모델에 대한 aoss:ExecuteMLResource 권한이 필요합니다. 이는 문서 인덱싱, 실행 _simulate및 검색에 적용됩니다. 이 권한이 없으면 누락된 권한의 이름을 지정하지 않는 Forbidden 오류와 함께 이러한 요청이 실패합니다.

다음 예제 데이터 액세스 정책은 보안 주체에게 컬렉션에서 파이프라인을 관리하고 해당 컬렉션에서 모델을 실행할 수 있는 권한을 부여합니다. collection-name을 컬렉션 이름으로, account-id를 AWS 계정 ID로, role-name을 파이프라인을 관리하고 사용하는 IAM 역할 이름으로 바꿉니다.

[ { "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" ] } ]

OpenSearch API 작업을 OpenSearch Serverless 권한에 완전히 매핑하려면 섹션을 참조하세요Amazon OpenSearch Serverless에서 지원되는 작업 및 플러그인.

문제 해결

ml_inference 파이프라인을 사용하는 요청이 Forbidden 오류와 함께 실패하는 경우 다음과 같은 일반적인 원인을 확인합니다.

  • 호출 보안 주체는 모델에 aoss:ExecuteMLResource가 없습니다. 에 표시된 대로 데이터 액세스 정책에 model 규칙을 추가합니다필수 권한.

  • 데이터 액세스 정책은 보안 주체에게 문서 작성, 검색 또는 파이프라인 생성과 같은 작업에 대한 인덱스 또는 컬렉션 권한을 부여하지 않습니다.

  • 요청은 es 대신 서비스 이름으로 서명됩니다aoss.

  • 컬렉션의 네트워크 정책은 요청 소스로부터의 액세스를 허용하지 않습니다.

파이프라인을 생성한 직후 Pipeline my-pipeline is not defined 오류와 함께 검색 요청이 실패하면 몇 분 정도 기다렸다가 다시 시도하세요. 자세한 내용은 검색 파이프라인에서 ml_inference 사용 섹션을 참조하세요.

자세한 정보

ml_inference 프로세서에 대한 자세한 내용은 다음을 참조하십시오.