Connector blueprints

출처: 문서

본문

커넥터 블루프린트

2.9에 도입됨 {: .label .label-purple }

모든 커넥터는 _커넥터 블루프린트_로 지정돼요. 블루프린트는 커넥터를 생성할 때 제공해야 하는 모든 파라미터를 정의해요.

예를 들어 다음 블루프린트는 Amazon SageMaker 커넥터에 대한 명세예요:

{
  "name": "<YOUR CONNECTOR NAME>",
  "description": "<YOUR CONNECTOR DESCRIPTION>",
  "version": "<YOUR CONNECTOR VERSION>",
  "protocol": "aws_sigv4",
  "credential": {
    "access_key": "<YOUR AWS ACCESS KEY>",
    "secret_key": "<YOUR AWS SECRET KEY>",
    "session_token": "<YOUR AWS SECURITY TOKEN>"
  },
  "parameters": {
    "region": "<YOUR AWS REGION>",
    "service_name": "sagemaker"
  },
  "actions": [
    {
      "action_type": "predict",
      "method": "POST",
      "headers": {
        "content-type": "application/json"
      },
      "url": "<YOUR SAGEMAKER MODEL ENDPOINT URL>",
      "request_body": "<YOUR REQUEST BODY. Example: ${parameters.inputs}>"
    }
  ]
}

{% include copy-curl.html %}

블루프린트 찾기

OpenSearch는 다양한 머신러닝(ML) 플랫폼과 모델을 위한 커넥터 블루프린트를 제공해요. 블루프린트가 제공되는 모든 플랫폼과 모델 목록, 그리고 각각이 사용하는 인증 프로토콜은 OpenSearch에서 제공하는 커넥터 블루프린트를 참고하세요.

ML 개발자라면 다른 플랫폼을 위한 커넥터 블루프린트를 직접 만들 수도 있어요. 이렇게 만든 블루프린트를 사용하면 관리자와 데이터 과학자가 해당 플랫폼에서 호스팅되는 모델의 커넥터를 생성할 수 있어요.

요청 본문 필드

다음 표는 커넥터 생성 요청의 필드를 나열한 거예요.

actions 객체는 다음 필드를 지원해요.

client_config 객체는 다음 필드를 지원해요.

내장 전처리 및 후처리 함수

다음 텍스트 임베딩 모델이나 원격 서버(예: Amazon SageMaker)에 배포한 자체 텍스트 임베딩 모델에 연결할 때는 커스텀 Painless 스크립트를 직접 작성하는 대신 내장 전처리 및 후처리 함수를 호출하세요.

• OpenAI 모델
• Cohere 모델

OpenSearch는 다음과 같은 전처리 및 후처리 함수를 제공해요:

• OpenAI: connector.pre_process.openai.embedding 및 connector.post_process.openai.embedding
• Cohere: connector.pre_process.cohere.embedding 및 connector.post_process.cohere.embedding
• neural search용 Amazon SageMaker 기본 함수: connector.pre_process.default.embedding 및 connector.post_process.default.embedding

neural search용 Amazon SageMaker 기본 전처리 및 후처리 함수

neural search를 사용해 벡터 검색을 수행하면 neural search 요청이 먼저 ML Commons로 라우팅된 다음 모델로 전달돼요. 모델이 OpenSearch에서 제공하는 사전 학습 모델 중 하나라면 ML Commons 요청을 파싱하고 ML Commons가 기대하는 형식으로 응답을 반환할 수 있어요. 하지만 외부 플랫폼에서 호스팅되는 모델은 기대하는 형식이 ML Commons 형식과 다를 수 있어요. 기본 전처리 및 후처리 함수는 모델이 기대하는 형식과 neural search가 기대하는 형식 사이를 상호 변환해 줘요.

기본 함수가 적용되려면 모델의 입력과 출력이 다음 섹션에서 설명하는 형식을 따라야 해요.

요청 예시

다음 예시 요청은 SageMaker 텍스트 임베딩 커넥터를 생성하고 기본 후처리 함수를 호출해요:

POST /_plugins/_ml/connectors/_create
{
  "name": "Sagemaker text embedding connector",
  "description": "The connector to Sagemaker",
  "version": 1,
  "protocol": "aws_sigv4",
  "credential": {
    "access_key": "<YOUR SAGEMAKER ACCESS KEY>",
    "secret_key": "<YOUR SAGEMAKER SECRET KEY>",
    "session_token": "<YOUR AWS SECURITY TOKEN>"
  },
  "parameters": {
    "region": "ap-northeast-1",
    "service_name": "sagemaker"
  },
  "actions": [
    {
      "action_type": "predict",
      "method": "POST",
      "url": "sagemaker.ap-northeast-1.amazonaws.com/endpoints/",
      "headers": {
        "content-type": "application/json"
      },
      "post_process_function": "connector.post_process.default.embedding",
      "request_body": "${parameters.input}"
    }
  ]
}

{% include copy-curl.html %}

request_body 템플릿은 ${parameters.input}여야 해요. {: .important}

전처리 함수

connector.pre_process.default.embedding 기본 전처리 함수는 neural search 요청을 파싱해서 모델이 입력으로 기대하는 형식으로 변환해요.

ML Commons Predict API는 다음 형식으로 파라미터를 제공해요:

{
  "parameters": {
    "input": ["hello", "world"]
  }
}

기본 전처리 함수는 input 필드 내용을 모델에 보내요. 따라서 모델 입력 형식은 문자열 리스트여야 해요. 예를 들면 다음과 같아요:

["hello", "world"]

후처리 함수

connector.post_process.default.embedding 기본 후처리 함수는 모델 응답을 파싱해서 neural search가 입력으로 기대하는 형식으로 변환해요.

원격 텍스트 임베딩 모델의 출력은 2차원 float 배열이어야 하고, 각 요소는 입력 리스트에 있는 문자열 하나의 임베딩을 나타내요. 예를 들어 다음 2차원 배열은 ["hello", "world"] 리스트의 임베딩에 해당해요:

[
  [
    -0.048237994,
    -0.07612697,
    ...
  ],
  [
    0.32621247,
    0.02328475,
    ...
  ]
]

커스텀 전처리 및 후처리 함수

모델 형식에 맞춰 자체 전처리 및 후처리 함수를 직접 작성할 수도 있어요. 예를 들어 다음 Amazon Bedrock 커넥터 정의에는 Amazon Bedrock Titan 임베딩 모델용 커스텀 전처리 및 후처리 함수가 포함되어 있어요:

POST /_plugins/_ml/connectors/_create
{
  "name": "Amazon Bedrock Connector: embedding",
  "description": "The connector to the Bedrock Titan embedding model",
  "version": 1,
  "protocol": "aws_sigv4",
  "parameters": {
    "region": "<YOUR AWS REGION>",
    "service_name": "bedrock"
  },
  "credential": {
    "access_key": "<YOUR AWS ACCESS KEY>",
    "secret_key": "<YOUR AWS SECRET KEY>",
    "session_token": "<YOUR AWS SECURITY TOKEN>"
  },
  "actions": [
    {
      "action_type": "predict",
      "method": "POST",
      "url": "https://bedrock-runtime.us-east-1.amazonaws.com/model/amazon.titan-embed-text-v1/invoke",
      "headers": {
        "content-type": "application/json",
        "x-amz-content-sha256": "required"
      },
      "request_body": "{ \"inputText\": \"${parameters.inputText}\" }",
      "pre_process_function": "\n    StringBuilder builder = new StringBuilder();\n    builder.append(\"\\\"\");\n    String first = params.text_docs[0];\n    builder.append(first);\n    builder.append(\"\\\"\");\n    def parameters = \"{\" +\"\\\"inputText\\\":\" + builder + \"}\";\n    return  \"{\" +\"\\\"parameters\\\":\" + parameters + \"}\";",
      "post_process_function": "\n      def name = \"sentence_embedding\";\n      def dataType = \"FLOAT32\";\n      if (params.embedding == null || params.embedding.length == 0) {\n        return params.message;\n      }\n      def shape = [params.embedding.length];\n      def json = \"{\" +\n                 \"\\\"name\\\":\\\"\" + name + \"\\\",\" +\n                 \"\\\"data_type\\\":\\\"\" + dataType + \"\\\",\" +\n                 \"\\\"shape\\\":\" + shape + \",\" +\n                 \"\\\"data\\\":\" + params.embedding +\n                 \"}\";\n      return json;\n    "
    }
  ]
}

{% include copy-curl.html %}

다음 단계

• 외부 모델 연결에 대해 더 자세히 알아보려면 외부 호스팅 모델 연결을 참조하세요.
• 커넥터 예시는 커넥터를 참조하세요.

더 알아보기 (Learn more)

• 원문 전체: https://docs.opensearch.org/latest/ml-commons-plugin/remote-models/blueprints/