패키지 권한 요구 사항 Amazon S3에 패키지 업로드 패키지 가져오기 및 연결 다음과 같은 패키지 사용 OpenSearch 사용자 지정 패키지 업데이트 수동 사전 인덱스 업데이트 패키지 분리 및 제거

아마존 OpenSearch 서비스용 커스텀 패키지

Amazon OpenSearch Service에서는 불용어 및 동의어와 같은 사용자 지정 사전 파일을 업로드할 수 있으며 도메인과 연결할 수 있는 사전 패키징된 선택적 플러그인도 여러 개 제공합니다. 이러한 유형의 파일을 일반적으로 패키지로 일컫습니다.

사전 파일은 자주 사용하는 특정 단어를 무시하거나 “프로즌 커스터드”, “젤라토”, “아이스크림”과 같은 용어를 동등한 것으로 취급하도록 OpenSearch 지시하여 검색 결과를 개선합니다. 또한 Japanese (kuromoji) Analysis 플러그인과 같이 어간 추출을 개선할 수 있습니다.

선택적 플러그인은 도메인에 추가 기능을 제공할 수 있습니다. 예를 들어 Amazon Personalize 플러그인을 사용하여 개인화된 검색 결과를 제공할 수 있습니다. 선택적 플러그인은 ZIP-PLUGIN 패키지 유형을 사용합니다. 플러그인에 대한 자세한 내용은 Amazon OpenSearch 서비스의 엔진 버전별 플러그인 섹션을 참조하세요.

패키지 권한 요구 사항

관리자 액세스 권한이 없는 사용자는 패키지를 관리하기 위해 특정 AWS Identity and Access Management (IAM) 작업이 필요합니다.

es:CreatePackage- OpenSearch 서비스 지역에서 패키지 생성
es:DeletePackage- OpenSearch 서비스 지역에서 패키지 삭제
es:AssociatePackage - 패키지를 도메인에 연결
es:DissociatePackage - 도메인에서 패키지 분리

또한 사용자 지정 패키지가 상주하는 Amazon S3 버킷 경로 또는 객체에 대한 권한도 필요합니다.

도메인 액세스 정책이 아닌 IAM 내에서 모든 권한을 부여합니다. 자세한 내용은 아마존 OpenSearch 서비스의 ID 및 액세스 관리 섹션을 참조하세요.

Amazon S3에 패키지 업로드

이 섹션에서는 선택적 플러그인 패키지가 이미 사전 설치되어 있으므로 사용자 지정 사전 패키지를 업로드하는 방법을 설명합니다. 패키지를 도메인에 연결하려면 먼저 Amazon S3 버킷에 패키지를 업로드해야 합니다. 지침은 Amazon Simple Storage Service 사용 설명서에서 객체 업로드를 참조하세요. 지원되는 플러그인을 업로드할 필요가 없습니다.

사전에 민감한 정보가 포함되어 있는 경우 업로드할 때 S3 관리 키를 사용한 서버 측 암호화를 지정하십시오. OpenSearch 서비스는 키를 사용하여 보호하는 S3의 파일에 액세스할 수 없습니다. AWS KMS

파일을 업로드한 후 S3 경로를 기록해 둡니다. 경로 형식은 s3://bucket-name/file-path/file-name입니다.

테스트 용도로 다음 동의어 파일을 사용할 수 있습니다. synonyms.txt로 파일을 저장합니다.


danish, croissant, pastry
ice cream, gelato, frozen custard
sneaker, tennis shoe, running shoe
basketball shoe, hightop

Hunspell 사전과 같은 특정 사전은 여러 파일을 사용하며 파일 시스템에 자체 디렉터리가 필요합니다. 현재 OpenSearch 서비스는 단일 파일 딕셔너리만 지원합니다.

패키지 가져오기 및 연결

콘솔은 사용자 지정 사전을 Service로 가져오는 가장 간단한 방법입니다. OpenSearch Amazon S3에서 사전을 가져오면 서비스는 패키지의 자체 사본을 저장하고 OpenSearch 서비스 OpenSearch 관리 키가 있는 AES-256 을 사용하여 해당 사본을 자동으로 암호화합니다.

선택적 플러그인은 OpenSearch 서비스에 이미 사전 설치되어 있으므로 직접 업로드할 필요는 없지만 플러그인을 도메인과 연결해야 합니다. 사용 가능한 플러그인은 콘솔의 패키지 화면에 나열되어 있습니다.

Amazon OpenSearch 서비스 콘솔에서 패키지를 선택합니다.
[패키지 가져오기(Import package)]를 선택합니다.
사용자 지정 사전에 설명 이름을 지정합니다.
파일에 대한 S3 경로를 지정한 다음 [제출(Submit)]을 선택합니다.
패키지(Packages) 화면으로 돌아갑니다.
패키지 상태가 사용 가능(Available)인 경우 패키지를 선택합니다. 선택적 플러그인은 자동으로 사용할 수 있습니다.
그런 다음 도메인에 연결을 선택합니다.
도메인을 선택한 다음 [연결(Associate)]을 선택합니다.
탐색 창에서 해당하는 도메인을 선택하고 패키지(Packages) 탭으로 이동합니다.
패키지가 사용자 지정 사전인 경우 패키지가 사용 가능한 상태가 되면 ID를 기록해 두세요. 요청 대상 파일 analyzers/id 경로로 사용합니다 OpenSearch.

또는 AWS CLI, SDK 또는 구성 API를 사용하여 패키지를 가져오고 연결할 수도 있습니다. 자세한 내용은 AWS CLI 명령 참조 및 Amazon OpenSearch 서비스 API 참조를 참조하십시오.

다음과 같은 패키지 사용 OpenSearch

이 섹션에서는 사용자 지정 사전과 선택적 플러그인과 같은 두 가지 유형의 패키지를 모두 사용하는 방법을 다룹니다.

사용자 지정 사전

파일을 도메인에 연결한 후에는 토크나이저 및 토큰 필터를 생성할 때 synonyms_path, stopwords_path, user_dictionary와 같은 파라미터에 해당 파일을 사용할 수 있습니다. 정확한 파라미터는 객체에 따라 다릅니다. 몇 가지 객체는 synonyms_path 및 stopwords_path를 지원하지만 user_dictionary는 kuromoji 플러그인에만 사용됩니다.

IK(중국어) 분석 플러그인의 경우 사용자 지정 사전 파일을 사용자 지정 패키지로 업로드하고 도메인에 연결할 수 있으며 user_dictionary 파라미터를 요구하지 않고 플러그인이 파일을 자동으로 선택합니다. 파일이 동의어 파일인 경우 synonyms_path 파라미터를 사용합니다.

다음 예제는 새 인덱스에 동의어 파일을 추가합니다.


PUT my-index
{
  "settings": {
    "index": {
      "analysis": {
        "analyzer": {
          "my_analyzer": {
            "type": "custom",
            "tokenizer": "standard",
            "filter": ["my_filter"]
          }
        },
        "filter": {
          "my_filter": {
            "type": "synonym",
            "synonyms_path": "analyzers/F111111111",
            "updateable": true
          }
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "description": {
        "type": "text",
        "analyzer": "standard",
        "search_analyzer": "my_analyzer"
      }
    }
  }
}

이 요청은 표준 토크나이저 및 동의어 토큰 필터를 사용하는 인덱스에 대한 사용자 지정 분석기를 생성합니다.

토크나이저는 일련의 규칙에 따라 문자 스트림을 토큰(일반적으로 단어)으로 나눕니다. 가장 간단한 예는 공백 문자를 만날 때마다 앞의 문자를 토큰으로 나누는 공백 토크나이저입니다. 더욱 복잡한 예는 여러 언어에 걸쳐 일련의 문법 기반 규칙을 사용하는 표준 토크나이저입니다.
토큰 필터는 토큰을 추가, 수정 또는 삭제합니다. 예를 들어 동의어 토큰 필터는 동의어 목록에서 단어를 찾으면 토큰을 추가합니다. 중단 토큰 필터는 불용어 목록의 단어를 찾으면 토큰을 제거합니다.

또한 이 요청은 매핑에 텍스트 필드 (description) 를 추가하고 새 분석기를 검색 분석기로 사용하도록 OpenSearch 지시합니다. 여전히 표준 분석기를 인덱스 분석기로 사용할 수 있습니다.

마지막으로 토큰 필터에 "updateable": true줄을 기록해 둡니다. 이 필드는 인덱스 분석기가 아닌 검색 분석기에만 적용되며 추후 자동으로 검색 분석기를 업데이트하고자 할 때 중요합니다.

테스트를 위해 인덱스에 몇 가지 문서를 추가합니다.


POST _bulk
{ "index": { "_index": "my-index", "_id": "1" } }
{ "description": "ice cream" }
{ "index": { "_index": "my-index", "_id": "2" } }
{ "description": "croissant" }
{ "index": { "_index": "my-index", "_id": "3" } }
{ "description": "tennis shoe" }
{ "index": { "_index": "my-index", "_id": "4" } }
{ "description": "hightop" }

그런 다음 동의어를 사용하여 문서를 검색하세요.


GET my-index/_search
{
  "query": {
    "match": {
      "description": "gelato"
    }
  }
}

이 경우 는 다음 OpenSearch 응답을 반환합니다.


{
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0.99463606,
    "hits": [{
      "_index": "my-index",
      "_type": "_doc",
      "_id": "1",
      "_score": 0.99463606,
      "_source": {
        "description": "ice cream"
      }
    }]
  }
}

작은 정보

사전 파일은 크기에 비례하여 Java 힙 공간을 사용합니다. 예를 들어, 2GiB 사전 파일은 노드에서 2GiB의 힙 공간을 사용할 수 있습니다. 큰 파일을 사용하는 경우 노드에 해당 파일을 수용할 수 있는 충분한 힙 공간이 있는지 확인합니다. JVMMemoryPressure 지표를 모니터링하고 필요에 따라 클러스터를 확장합니다.

선택적 플러그인 사용

OpenSearch 서비스를 통해 사전 설치된 선택적 OpenSearch 플러그인을 도메인과 연결하여 사용할 수 있습니다. 선택적 플러그인 패키지는 특정 OpenSearch 버전과 호환되며 해당 버전의 도메인에만 연결할 수 있습니다. 도메인에 사용할 수 있는 패키지 목록에는 도메인 버전과 호환되는 모든 지원 플러그인이 포함됩니다. 플러그인을 도메인에 연결한 후에 도메인에서의 설치 프로세스가 시작됩니다. 그러면 OpenSearch 서비스에 요청할 때 플러그인을 참조하고 사용할 수 있습니다.

플러그인을 연결하고 분리하려면 블루/그린 배포가 필요합니다. 자세한 정보는 블루/그린 배포의 원인이 되는 변경 사항을 참조하세요.

선택적 플러그인에는 언어 분석기 및 사용자 지정 검색 결과가 포함됩니다. 예를 들어 Amazon Personalize Search Ranking 플러그인은 기계 학습을 사용하여 고객을 위한 검색 결과를 개인화합니다. 이 플러그인에 대한 자세한 내용은 검색 결과 맞춤 설정을 참조하십시오. OpenSearch 지원되는 인스턴스 전체 목록은 Amazon OpenSearch 서비스의 엔진 버전별 플러그인 섹션을 참조하세요.

Sudachi 플러그인

Sudachi 플러그인의 경우 사전 파일을 다시 연결해도 도메인에 즉시 반영되지 않습니다. 구성 변경 또는 기타 업데이트의 일환으로 도메인에서 다음 블루/그린 배포가 실행되면 사전이 새로 고쳐집니다. 또는 업데이트된 데이터로 새 패키지를 만들고, 이 새 패키지를 사용하여 새 색인을 만들고, 기존 색인을 새 색인으로 다시 색인화한 다음 이전 색인을 삭제할 수 있습니다. 재인덱싱 방식을 사용하려는 경우 트래픽이 중단되지 않도록 인덱스 별칭을 사용하세요.

또한 Sudachi 플러그인은 API 작업을 통해 업로드할 수 있는 이진 Sudachi 사전만 지원합니다. CreatePackage 사전 빌드된 시스템 사전 및 사용자 사전 컴파일 프로세스에 대한 자세한 내용은 Sudachi 설명서를 참조하세요.

다음 예제는 Sudachi 토큰화에서 시스템 및 사용자 사전을 사용하는 방법을 보여줍니다. 이러한 사전을 TXT-DICTIONARY 유형의 사용자 지정 패키지로 업로드하고 추가 설정에서 해당 패키지 ID를 제공해야 합니다.


PUT sudachi_sample
{
  "settings": {
    "index": {
      "analysis": {
        "tokenizer": {
          "sudachi_tokenizer": {
            "type": "sudachi_tokenizer",
            "additional_settings": "{\"systemDict\": \"<system-dictionary-package-id>\",\"userDict\": [\"<user-dictionary-package-id>\"]}"
        }
        },
        "analyzer": {
          "sudachi_analyzer": {
            "filter": ["my_searchfilter"],
            "tokenizer": "sudachi_tokenizer",
            "type": "custom"
          }
        },
        "filter":{
          "my_searchfilter": {
            "type": "sudachi_split",
            "mode": "search"
          }
        }
      }
    }
  }
}

사용자 지정 패키지 업데이트

선택적 플러그인 패키지는 이미 업데이트되었으므로 이 섹션에서는 사용자 지정 사전 패키지를 업데이트하는 방법만 다룹니다. 새 버전의 사전을 Amazon S3에 업로드해도 Amazon Service의 패키지는 자동으로 업데이트되지 않습니다. OpenSearch OpenSearch 서비스는 파일의 자체 사본을 저장하므로 S3에 새 버전을 업로드하는 경우 수동으로 업데이트해야 합니다.

연결된 각 도메인은 해당 파일의 자체 복사본도 저장합니다. 검색 동작을 예측할 수 있게 유지하기 위해 도메인은 명시적으로 업데이트할 때까지 현재 패키지 버전을 계속 사용합니다. 사용자 지정 패키지를 업데이트하려면 에서 Amazon S3 Control파일을 수정하고 OpenSearch 서비스에서 패키지를 업데이트한 다음 업데이트를 적용하십시오.

OpenSearch 서비스 콘솔에서 패키지를 선택합니다.
패키지를 선택하고 [업데이트(Update)]를 선택합니다.
파일에 대한 S3 경로를 지정한 다음 패키지 업데이트(Update package)를 선택합니다.
패키지(Packages) 화면으로 돌아갑니다.
패키지 상태가 사용 가능(Available)으로 변경되면 패키지를 선택합니다. 그런 다음 하나 이상의 연결된 도메인을 선택하고 업데이트 적용(Apply update)을 선택한 다음, 확인합니다. 연결 상태가 활성(Active)으로 변경될 때까지 기다립니다.
다음 단계는 인덱스를 구성하는 방식에 따라 달라집니다.
- 도메인이 실행 OpenSearch 중이거나 Elasticsearch 7.8 이상을 실행 중이고 업데이트 가능 필드가 true로 설정된 검색 분석기만 사용하는 경우에는 추가 조치를 취할 필요가 없습니다. OpenSearch 서비스는 _plugins/_refresh_search_analyzers API를 사용하여 인덱스를 자동으로 업데이트합니다.
- 도메인에서 Elasticsearch 7.7 이전 버전을 실행하거나, 인덱스 분석기를 사용하거나, 필드를 사용하지 않는 경우에는 을 참조하십시오. updateable 수동 사전 인덱스 업데이트

콘솔이 가장 간단한 방법이긴 하지만 AWS CLI, SDK 또는 구성 API를 사용하여 서비스 패키지를 업데이트할 수도 있습니다. OpenSearch 자세한 내용은 AWS CLI 명령 참조 및 Amazon OpenSearch 서비스 API 참조를 참조하십시오.

콘솔에서 패키지를 수동으로 업데이트하는 대신 SDK를 사용하여 업데이트 프로세스를 자동화할 수 있습니다. 다음 샘플 Python 스크립트는 Amazon S3에 새 패키지 파일을 업로드하고, OpenSearch Service에서 패키지를 업데이트하고, 새 패키지를 지정된 도메인에 적용합니다. 업데이트가 성공적으로 완료되었는지 확인한 후 샘플 호출을 통해 새 동의어가 적용되었는지 OpenSearch 보여줍니다.

host, region, file_name, bucket_name, s3_key, package_id, domain_name, query의 값을 입력해야 합니다.


from requests_aws4auth import AWS4Auth
import boto3
import requests
import time
import json
import sys

host = ''  # The OpenSearch domain endpoint with https:// and a trailing slash. For example, https://my-test-domain.us-east-1.es.amazonaws.com/
region = ''  # For example, us-east-1
file_name = ''  # The path to the file to upload
bucket_name = ''  # The name of the S3 bucket to upload to
s3_key = ''  # The name of the S3 key (file name) to upload to
package_id = ''  # The unique identifier of the OpenSearch package to update
domain_name = ''  # The domain to associate the package with
query = ''  # A test query to confirm the package has been successfully updated

service = 'es'
credentials = boto3.Session().get_credentials()
client = boto3.client('opensearch')
awsauth = AWS4Auth(credentials.access_key, credentials.secret_key,
                   region, service, session_token=credentials.token)


def upload_to_s3(file_name, bucket_name, s3_key):
    """Uploads file to S3"""
    s3 = boto3.client('s3')
    try:
        s3.upload_file(file_name, bucket_name, s3_key)
        print('Upload successful')
        return True
    except FileNotFoundError:
        sys.exit('File not found. Make sure you specified the correct file path.')


def update_package(package_id, bucket_name, s3_key):
    """Updates the package in OpenSearch Service"""
    print(package_id, bucket_name, s3_key)
    response = client.update_package(
        PackageID=package_id,
        PackageSource={
            'S3BucketName': bucket_name,
            'S3Key': s3_key
        }
    )
    print(response)


def associate_package(package_id, domain_name):
    """Associates the package to the domain"""
    response = client.associate_package(
        PackageID=package_id, DomainName=domain_name)
    print(response)
    print('Associating...')


def wait_for_update(domain_name, package_id):
    """Waits for the package to be updated"""
    response = client.list_packages_for_domain(DomainName=domain_name)
    package_details = response['DomainPackageDetailsList']
    for package in package_details:
        if package['PackageID'] == package_id:
            status = package['DomainPackageStatus']
            if status == 'ACTIVE':
                print('Association successful.')
                return
            elif status == 'ASSOCIATION_FAILED':
                sys.exit('Association failed. Please try again.')
            else:
                time.sleep(10)  # Wait 10 seconds before rechecking the status
                wait_for_update(domain_name, package_id)


def sample_search(query):
    """Makes a sample search call to OpenSearch"""
    path = '_search'
    params = {'q': query}
    url = host + path
    response = requests.get(url, params=params, auth=awsauth)
    print('Searching for ' + '"' + query + '"')
    print(response.text)

참고

를 사용하여 스크립트를 실행할 때 “패키지를 찾을 수 없음” 오류가 발생하면 Boto3가 ~/.aws/config에 지정된 지역 AWS CLI, 즉 S3 버킷이 속한 지역이 아닌 지역을 사용하고 있다는 의미일 수 있습니다. aws configure를 실행하고 올바른 리전을 지정하거나 다음 클라이언트에 리전을 명시적으로 추가하세요.


client = boto3.client('opensearch', region_name='us-east-1')

수동 사전 인덱스 업데이트

수동 인덱스 업데이트는 사용자 지정 사전에만 적용되며 선택적 플러그인에는 적용되지 않습니다. 업데이트된 패키지를 사용하려면 다음 조건 중 하나를 충족하는 경우 인덱스를 수동으로 업데이트해야 합니다.

도메인에서 Elasticsearch 7.7 이전 버전이 실행됩니다.
사용자 지정 패키지를 인덱스 분석기로 사용합니다.
사용자 지정 패키지를 검색 분석기로 사용하지만 업데이트 가능 필드를 포함하지 않습니다.

새 패키지 파일로 분석기를 업데이트하기 위해 다음 두 가지 옵션을 사용할 수 있습니다.

업데이트하려는 인덱스를 모두 닫고 엽니다.
```
POST my-index/_close
POST my-index/_open
```

인덱스를 다시 생성합니다. 먼저 업데이트된 동의어 파일(또는 전혀 새로운 파일)을 사용하는 인덱스를 생성합니다. UTF-8 버전만 지원됩니다.


PUT my-new-index
{
  "settings": {
    "index": {
      "analysis": {
        "analyzer": {
          "synonym_analyzer": {
            "type": "custom",
            "tokenizer": "standard",
            "filter": ["synonym_filter"]
          }
        },
        "filter": {
          "synonym_filter": {
            "type": "synonym",
            "synonyms_path": "analyzers/F222222222"
          }
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "description": {
        "type": "text",
        "analyzer": "synonym_analyzer"
      }
    }
  }
}

그런 다음 이전 인덱스를 새 인덱스로 다시 생성합니다.


POST _reindex
{
  "source": {
    "index": "my-index"
  },
  "dest": {
    "index": "my-new-index"
  }
}

인덱스 분석기를 자주 업데이트하는 경우 인덱스 별칭을 사용하여 최신 인덱스에 대한 일관된 경로를 유지합니다.


POST _aliases
{
  "actions": [
    {
      "remove": {
        "index": "my-index",
        "alias": "latest-index"
      }
    },
    {
      "add": {
        "index": "my-new-index",
        "alias": "latest-index"
      }
    }
  ]
}

이전 인덱스가 필요하지 않으면 삭제합니다.


DELETE my-index

패키지 분리 및 제거

도메인에서 패키지를 분리하면 새 인덱스를 생성할 때 해당 파일을 더 이상 사용할 수 없습니다. 패키지 연결이 해제되면 해당 패키지를 사용하던 기존 인덱스는 더 이상 패키지를 사용할 수 없습니다. 패키지를 분리하려면 먼저 색인에서 패키지를 제거해야 합니다. 그렇지 않으면 연결 해제가 실패합니다.

콘솔은 도메인에서 패키지를 분리하고 서비스에서 패키지를 제거하는 가장 간단한 방법입니다. OpenSearch OpenSearch 서비스에서 패키지를 제거해도 Amazon S3의 원래 위치에서 제거되지는 않습니다.

https://aws.amazon.com으로 이동하여 콘솔에 로그인(Sign In to the Console)을 선택합니다.
애널리틱스에서 Amazon OpenSearch 서비스를 선택합니다.
탐색 창에서 해당하는 도메인을 선택한 다음 패키지(Packages) 탭을 선택합니다.
패키지, 작업(Actions), 분리(Dissociate)를 차례로 선택합니다. 선택 내용을 확인합니다.
패키지가 목록에서 사라질 때까지 기다립니다. 브라우저를 새로 고쳐야 할 수 있습니다.
패키지를 다른 도메인에 사용하려면 여기에서 작업을 중지합니다. 계속해서 패키지를 제거하려면 탐색 창에서 패키지를 선택합니다.
패키지를 선택하고 삭제(Delete)를 선택합니다.

또는 AWS CLI, SDK 또는 구성 API를 사용하여 패키지를 분리하고 제거할 수도 있습니다. 자세한 내용은 AWS CLI 명령 참조 및 Amazon OpenSearch 서비스 API 참조를 참조하십시오.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

데이터 검색

SQL 지원