opensearch-py-ml

개요

opensearch-py-ml은 OpenSearch를 위한 Python 데이터 분석 및 머신러닝 클라이언트 라이브러리다. Eland의 커뮤니티 주도 오픈소스 포크로, Apache v2.0 라이선스 하에 배포된다.

Eland가 Elasticsearch 전용인 것과 달리, opensearch-py-ml은 OpenSearch를 위해 특별히 개발되었으며 OpenSearch의 ML Commons 플러그인과 긴밀하게 통합되어 있다.

주요 기능

1. DataFrame API

OpenSearch 인덱스를 Pandas DataFrame처럼 다룰 수 있는 API를 제공한다. Jupyter Notebook 환경에서 대용량 데이터를 효율적으로 분석할 수 있다.

특징:

• Pandas와 유사한 인터페이스
• OpenSearch에서 직접 데이터 처리 수행
• 복잡한 필터링 및 집계 연산 지원
• 메모리 제약 없이 대용량 데이터 처리

2. ML Commons 통합

OpenSearch의 ML Commons 플러그인과 통합하여 머신러닝 모델을 관리하고 사용할 수 있다.

지원 기능:

• 사전 학습된 모델 등록
• 모델 배포 및 언로드
• 임베딩 생성 및 추론
• 모델 그룹 관리
• 모델 삭제

3. SentenceTransformer 지원

SentenceTransformer 모델을 업로드하고 학습할 수 있다.

기능:

• Hugging Face의 SentenceTransformer 모델 업로드
• 합성 쿼리를 사용한 모델 파인튜닝
• 텍스트 임베딩 생성

설치

# opensearch-py-ml 설치
pip install opensearch-py-ml
 
# OpenSearch Python 클라이언트도 함께 설치됨

요구사항:

• Python 3.x
• opensearch-py (자동으로 설치됨)
• OpenSearch 클러스터 (1.x, 2.x 지원)

사용 예시

DataFrame으로 데이터 조회

from opensearchpy import OpenSearch
import opensearch_py_ml as oml
 
# OpenSearch 연결
client = OpenSearch(
    hosts=[{'host': 'localhost', 'port': 9200}],
    http_auth=('admin', 'admin'),
    use_ssl=True,
    verify_certs=False
)
 
# DataFrame 생성
oml_df = oml.DataFrame(client, 'my-index')
 
# 데이터 조회
print(oml_df.head())
 
# 필터링 및 집계
filtered = oml_df[oml_df['age'] > 30]
result = filtered.groupby('city').mean()
print(result)

Pandas와 상호 변환

import pandas as pd
import opensearch_py_ml as oml
 
# Pandas DataFrame을 OpenSearch에 저장
pd_df = pd.DataFrame({
    'name': ['Alice', 'Bob', 'Charlie'],
    'age': [25, 30, 35],
    'city': ['Seoul', 'Busan', 'Incheon']
})
 
oml.pandas_to_opensearch(
    pd_df,
    client,
    'users-index'
)
 
# OpenSearch에서 Pandas DataFrame으로 변환
oml_df = oml.DataFrame(client, 'users-index')
pd_df_result = oml.opensearch_to_pandas(oml_df)

사전 학습 모델 등록

from opensearchpy import OpenSearch
import opensearch_py_ml as oml
 
# OpenSearch 클라이언트 생성
client = OpenSearch(
    hosts=[{'host': 'localhost', 'port': 9200}],
    http_auth=('admin', 'admin')
)
 
# ML Commons 클라이언트 생성
ml_client = oml.MLCommonClient(client)
 
# 사전 학습 모델 등록
model_id = ml_client.register_pretrained_model(
    model_name="huggingface/sentence-transformers/all-MiniLM-L6-v2",
    model_version="1.0.0",
    model_format="TORCH_SCRIPT",
    deploy_model=True  # 등록 후 자동 배포
)
 
print(f"Model registered with ID: {model_id}")

모델 배포 및 언로드

# 모델 배포 (메모리에 로드)
task_id = ml_client.deploy_model(model_id)
 
# 배포 상태 확인
task_info = ml_client.get_task_info(task_id)
print(f"Deployment status: {task_info['state']}")
 
# 모델 정보 조회
model_info = ml_client.get_model_info(model_id)
print(model_info)
 
# 모델 언로드 (메모리에서 제거)
ml_client.undeploy_model(model_id)

임베딩 생성

# 텍스트 임베딩 생성
sentences = [
    "OpenSearch는 강력한 검색 엔진입니다",
    "머신러닝 모델을 쉽게 통합할 수 있습니다"
]
 
embeddings = ml_client.generate_embedding(
    model_id=model_id,
    sentences=sentences
)
 
print(f"Generated {len(embeddings)} embeddings")
print(f"Embedding dimension: {len(embeddings[0])}")

모델 그룹 관리

# 모델 그룹 생성 (OpenSearch 2.8+)
model_group_id = ml_client.register_model_group(
    name="sentence-transformers",
    description="Sentence transformer models for semantic search"
)
 
# 모델 그룹에 모델 등록
model_id = ml_client.register_pretrained_model(
    model_name="huggingface/sentence-transformers/msmarco-distilbert-base-v4",
    model_version="1.0.0",
    model_format="TORCH_SCRIPT",
    model_group_id=model_group_id
)

모델 삭제

# 모델 삭제 (언로드 후 영구 삭제)
ml_client.delete_model(model_id)
print(f"Model {model_id} deleted")

주요 활용 사례

1. 시맨틱 검색

SentenceTransformer 모델을 사용하여 의미 기반 검색을 구현할 수 있다.

# 1. 모델 등록 및 배포
model_id = ml_client.register_pretrained_model(
    model_name="huggingface/sentence-transformers/all-MiniLM-L6-v2",
    model_version="1.0.0",
    model_format="TORCH_SCRIPT",
    deploy_model=True
)
 
# 2. 문서 임베딩 생성 및 인덱싱
documents = [
    "Python is a programming language",
    "OpenSearch is a search engine",
    "Machine learning helps computers learn"
]
 
embeddings = ml_client.generate_embedding(model_id, documents)
 
# 3. 검색 시 쿼리 임베딩 생성하여 유사도 검색
query = "What is a search tool?"
query_embedding = ml_client.generate_embedding(model_id, [query])[0]

2. 대용량 로그 분석

OpenSearch에 저장된 대용량 로그 데이터를 Pandas와 유사한 방식으로 분석할 수 있다.

# 로그 데이터 조회
logs_df = oml.DataFrame(client, 'logs-2024-*')
 
# 에러 로그 필터링
error_logs = logs_df[logs_df['level'] == 'ERROR']
 
# 시간대별 에러 집계
hourly_errors = error_logs.groupby(
    pd.Grouper(key='timestamp', freq='1H')
).size()
 
print(hourly_errors)

3. 추천 시스템

사용자와 아이템을 임베딩하여 추천 시스템을 구축할 수 있다.

# 사용자 프로필 임베딩
user_profiles = [
    "User likes action movies and sci-fi",
    "User prefers comedy and romance"
]
 
user_embeddings = ml_client.generate_embedding(model_id, user_profiles)
 
# 아이템(영화) 설명 임베딩
movie_descriptions = [
    "Action-packed space adventure",
    "Romantic comedy about love"
]
 
movie_embeddings = ml_client.generate_embedding(model_id, movie_descriptions)
 
# 코사인 유사도로 추천

4. ETL 파이프라인

다양한 데이터 소스에서 데이터를 추출하여 OpenSearch로 로드할 수 있다.

import pandas as pd
import opensearch_py_ml as oml
 
# CSV 파일 읽기
df = pd.read_csv('data.csv')
 
# 데이터 변환
df['timestamp'] = pd.to_datetime(df['timestamp'])
df['category'] = df['category'].str.lower()
 
# OpenSearch에 로드
oml.pandas_to_opensearch(
    df,
    client,
    'processed-data',
    chunk_size=1000
)

Eland와의 비교

측면	Eland	opensearch-py-ml
대상 플랫폼	Elasticsearch	OpenSearch
라이선스	Elastic License 2.0	Apache 2.0
개발 주체	Elastic	OpenSearch Community
ML 플러그인	Elasticsearch ML	ML Commons
모델 배포	Hugging Face Hub 직접 통합	ML Commons API 사용
지원 버전	Elasticsearch 8+	OpenSearch 1.x, 2.x, 3.x
DataFrame API	Pandas 스타일	Pandas 스타일 (유사)

버전 호환성

OpenSearch 버전 지원

opensearch-py-ml은 opensearch-py 클라이언트에 의존하므로, 해당 클라이언트의 호환성을 따른다.

호환성 매트릭스:

opensearch-py-ml 버전	OpenSearch 버전	비고
1.0.0	2.4.0	공식 호환성 매트릭스에 명시
1.3.0 (최신)	1.x, 2.x, 3.x	opensearch-py 3.x 의존성을 통해 지원

버전별 주요 기능:

• OpenSearch 1.x: DataFrame API, 기본 ML 모델 업로드
• OpenSearch 2.x: ML Commons 고급 기능, 모델 그룹 (2.8+)
• OpenSearch 3.x: opensearch-py 3.x와 함께 호환 (단, 3.0에서 제거된 기능은 사용 불가)

참고사항:

• opensearch-py 3.x.x는 OpenSearch 1.0.0-3.x를 지원
• OpenSearch 주요 버전 업그레이드 시 제거된 기능이 있을 수 있으므로 릴리스 노트 확인 필요
• 최신 버전 호환성은 opensearch-py COMPATIBILITY.md 참고

Python 버전

• Python 3.7+
• 권장: Python 3.9 이상

의존성

• opensearch-py: OpenSearch Python 클라이언트
• pandas: DataFrame 조작
• numpy: 수치 연산

제약사항

• Pandas API 부분 호환: 모든 Pandas 기능을 지원하지 않음
• ML Commons 의존성: ML 기능은 ML Commons 플러그인 설치 필요
• OpenSearch 전용: Elasticsearch와 호환되지 않음
• 문서 부족: Eland에 비해 문서와 예제가 적음

ML Commons 설정

ML 모델을 사용하기 위해서는 OpenSearch 클러스터에서 특정 설정을 활성화해야 한다:

# 외부 URL에서 모델 등록 허용
PUT _cluster/settings
{
  "persistent": {
    "plugins.ml_commons.allow_registering_model_via_url": true
  }
}
 
# 로컬 파일에서 모델 등록 허용
PUT _cluster/settings
{
  "persistent": {
    "plugins.ml_commons.allow_registering_model_via_local_file": true
  }
}

참고 자료

• opensearch-py-ml GitHub
• opensearch-py-ml 공식 문서
• opensearch-py-ml API 문서
• ML Commons 플러그인 문서
• ML Commons Demo Notebook
• opensearch-py-ml PyPI