본문 바로가기
WIKI 기술 지식 베이스

Workload parameters

원문 보기 위키 갱신

출처: 문서

본문

워크로드 파라미터

워크로드 파라미터를 사용하면 워크로드 파일을 직접 수정하지 않고도 워크로드 동작을 커스터마이즈할 수 있어요. 런타임에 파라미터를 전달해서 벌크 크기, 샤드 수, 인덱스 이름, 검색 설정 같은 항목들을 제어할 수 있답니다.

OpenSearch Benchmark 워크로드는 Jinja2 템플릿을 사용해요. --workload-params 플래그로 파라미터를 전달하면, OpenSearch Benchmark가 실행 전에 이를 워크로드 JSON 파일에 주입해요.

예를 들어 워크로드의 index.json에는 다음과 같은 설정이 들어 있을 수 있어요:

{
  "settings": {
    "index.number_of_shards": {% raw %}{{ number_of_shards | default(1) }}{% endraw %},
    "index.number_of_replicas": {% raw %}{{ number_of_replicas | default(0) }}{% endraw %}
  }
}

--workload-params='{"number_of_shards": 3}'로 벤치마크를 실행하면, OpenSearch Benchmark가 {% raw %}{{ number_of_shards | default(1) }}{% endraw %}를 3으로 바꿔줘요. 오버라이드하지 않은 파라미터는 기본값을 그대로 사용해요.

파라미터 전달하기

파라미터는 다음과 같은 방법으로 전달할 수 있어요.

JSON 파일(파라미터가 많을 때 권장)

파라미터를 담은 JSON 파일을 만들어요:

{
  "number_of_shards": 3,
  "number_of_replicas": 1,
  "bulk_size": 5000,
  "target_index_name": "my_index"
}

{% include copy.html %}

그다음 다음과 같이 참조해요:

opensearch-benchmark run --workload=geonames --workload-params=my-params.json

{% include copy.html %}

인라인 JSON

명령줄에서 파라미터를 직접 전달해요:

opensearch-benchmark run --workload=geonames --workload-params='{"number_of_shards": 3, "bulk_size": 5000}'

{% include copy.html %}

쉼표로 구분된 키-값 쌍

키-값 쌍을 전달하려면 다음 형식을 사용해요:

opensearch-benchmark run --workload=geonames --workload-params="number_of_shards:3,bulk_size:5000"

{% include copy.html %}

쉼표로 구분하는 형식은 문자열 값만 지원해요. 숫자, 불리언 값, 중첩 객체에는 JSON 파일이나 인라인 JSON을 사용하세요. {: .note}

파라미터 우선순위

같은 파라미터가 여러 소스에서 정의되면, OpenSearch Benchmark는 다음 순서(우선순위가 높은 것부터)로 적용해요:

  1. --workload-params (CLI 플래그): 다른 모든 값을 오버라이드해요.
  2. 워크로드 템플릿 기본값: 워크로드 JSON 파일의 {% raw %}{{ var | default(value) }}{% endraw %} 표현식에 지정된 기본값(예: {% raw %}{{ number_of_shards | default(1) }}{% endraw %}).
  3. 정의되지 않음: 기본값도 지정되지 않고 파라미터도 제공되지 않으면, OpenSearch Benchmark가 템플릿 렌더링 오류를 발생시켜요.

템플릿 문법

이 섹션에서는 워크로드 파일에서 가장 많이 쓰이는 템플릿 패턴을 설명해요.

기본값이 있는 변수

default 필터를 사용하면 파라미터가 제공되지 않을 때의 대체(fallback) 값을 지정할 수 있어요. 예를 들어 --workload-params에 bulk_size가 제공되지 않으면, 이 표현식은 5000으로 평가돼요:

{% raw %}{{ bulk_size | default(5000) }}{% endraw %}

{% include copy.html %}

불리언 값

불리언 값에는 tojson 필터를 사용해서 올바른 JSON 출력을 보장하세요. 예를 들어 다음 표현식은 "false"가 아니라 false(따옴표 없음)로 평가돼요:

{% raw %}{{ query_cache_enabled | default(false) | tojson }}{% endraw %}

{% include copy.html %}

문자열 값

문자열 변수는 따옴표로 감싸요:

{% raw %}"{{ conflicts | default('random') }}"{% endraw %}

{% include copy.html %}

조건부 섹션

{% raw %}{% if %}{% endraw %} 블록을 사용하면 파라미터가 정의되어 있는지 여부나 파라미터 값에 따라 섹션을 포함하거나 제외할 수 있어요.

정의된 경우에만 필드 포함하기

다음 템플릿은 target-throughput 필드를 조건부로 포함해요. --workload-params로 target_throughput이 제공되지 않으면, 렌더링 결과에서 해당 필드 전체가 생략돼요:

{% raw %}{% if target_throughput is defined %}
"target-throughput": {{ target_throughput }},
{% endif %}{% endraw %}

{% include copy.html %}

대체 값을 위한 if/else

{% raw %}{% else %}{% endraw %}를 사용하면 대체 값을 제공할 수 있어요. 예를 들어 --workload-params에서 use_zstd가 true로 설정되면, 렌더링 결과에서 source-file 파라미터가 documents.json.zst로 설정돼요. 그렇지 않으면 source-file이 documents.json.bz2로 설정돼요:

{% raw %}{% if use_zstd %}
"source-file": "documents.json.zst",
{% else %}
"source-file": "documents.json.bz2",
{% endif %}{% endraw %}

{% include copy.html %}

조건부로 인덱스 필드 추가하기

이 패턴은 vectorsearch 워크로드 템플릿에서 선택적 필드를 정의할 때 흔히 사용돼요. {% raw %}{%- endif %}{% endraw %}(대시 포함)는 뒤따르는 공백과 줄바꿈 문자를 제거해서 빈 줄이 생기는 것을 막고, 잘못된 JSON 형식(후행 쉼표나 어긋난 구조 같은)을 방지해요:

"properties": {
  {% raw %}{% if id_field_name is defined and id_field_name != "_id" %}
  "{{ id_field_name }}": {
    "type": "keyword"
  },
  {%- endif %}{% endraw %}
  "embedding": {
    "type": "knn_vector",
    "dimension": {% raw %}{{ target_index_dimension }}{% endraw %}
  }
}

{% include copy.html %}

버전 기반 조건문

일부 워크로드는 distribution_version에 따라 동작을 조정해요. 이 값은 OpenSearch Benchmark가 대상 클러스터에 맞춰 자동으로 설정해요. 이 패턴을 사용하면 버전별 연산이나 설정을 조건부로 포함시켜 하나의 워크로드가 여러 OpenSearch 버전을 지원할 수 있어요:

{% raw %}{% if distribution_version is not defined %}
  {% set distribution_version = "2.11.0" %}
{% endif %}

{% if distribution_version.split('.') | map('int') | list >= "2.19.1".split('.') | map('int') | list %}
  {# Include features available in 2.19.1+ #}
{% endif %}{% endraw %}

{% include copy.html %}

for 루프

{% raw %}{% for %}{% endraw %} 루프를 사용하면 반복되는 구조를 생성할 수 있어요:

{% raw %}{% for i in range(1, 101) %}
{
  "name": "query-{{ i }}",
  "operation-type": "search",
  "body": { ... }
},
{% endfor %}{% endraw %}

{% include copy.html %}

정수 변환

파라미터가 반드시 정수여야 한다면 int 필터를 사용하세요:

{% raw %}{{ target_index_dimension | default(768) | int }}{% endraw %}

{% include copy.html %}

외부 파일 포함하기

워크로드는 보통 가독성을 위해 여러 파일로 나눠 구성돼요. {% raw %}{{ benchmark.collect }}{% endraw %} 헬퍼는 렌더링 시점에 여러 JSON 파일을 하나의 워크로드 정의로 합쳐줘요.

헬퍼 임포트하기

benchmark.collect를 사용하는 모든 workload.json은 파일 상단에서 이를 임포트해야 해요:

{% raw %}{% import "benchmark.helpers" as benchmark with context %}{% endraw %}

{% include copy.html %}

with context 절은 모든 워크로드 파라미터가 포함된 파일들에서 사용 가능하도록 보장해요.

연산과 테스트 프로시저 수집하기

일반적인 workload.json은 연산과 테스트 프로시저를 별도 파일에 위임해요:

{% raw %}{% import "benchmark.helpers" as benchmark with context %}{% endraw %}
{
  "version": 2,
  "description": "My workload",
  "indices": [ ... ],
  "corpora": [ ... ],
  "operations": [
    {% raw %}{{ benchmark.collect(parts="operations/*.json") }}{% endraw %}
  ],
  "test_procedures": [
    {% raw %}{{ benchmark.collect(parts="test_procedures/*.json") }}{% endraw %}
  ]
}

{% include copy.html %}

parts 인자는 glob 패턴을 받아요. operations/*.json 패턴은 operations/ 디렉터리의 모든 JSON 파일과 일치하며, 그 내용을 쉼표로 구분해서 포함시켜요. 이렇게 하면 연산과 테스트 프로시저 정의가 별도 파일에 정의되는 동안 메인 workload.json은 간결하게 유지돼요.

공유 파트로 스케줄 구성하기

테스트 프로시저는 공통 스케줄 조각을 재사용할 수 있어요. 예를 들어 vectorsearch 워크로드에는 test_procedures/common/ 아래에 공유 스케줄이 있어요:

test_procedures/
  common/
    index-only-schedule.json
    search-only-schedule.json
    force-merge-schedule.json
    vespa-search-only-schedule.json
  default.json

{% include copy.html %}

default.json의 테스트 프로시저는 이 파트들로 스케줄을 구성해요:

{
  "name": "no-train-test",
  "default": true,
  "schedule": [
    {% raw %}{{ benchmark.collect(parts="common/index-only-schedule.json") }}{% endraw %},
    {% raw %}{{ benchmark.collect(parts="common/force-merge-schedule.json") }}{% endraw %},
    {% raw %}{{ benchmark.collect(parts="common/search-only-schedule.json") }}{% endraw %}
  ]
}

{% include copy.html %}

수집된 각 파일에는 하나 이상의 스케줄 항목이 들어 있어요. 그 파일들 속의 {% raw %}{{ target_index_name }}{% endraw %} 같은 파라미터는 명령줄에서 전달한 동일한 --workload-params로 해석돼요. with context 임포트가 모든 파라미터를 포함된 파일들로 전파하기 때문이에요.

인덱스 바디 파일

인덱스 정의의 body 필드는 매핑과 설정을 담은 별도 JSON 파일을 참조해요:

"indices": [
  {
    "name": "geonames",
    "body": "index.json"
  }
]

{% include copy.html %}

index.json 파일도 다른 워크로드 파일과 마찬가지로 Jinja2 템플릿이라 파라미터를 사용할 수 있어요:

{
  "settings": {
    "index.number_of_shards": {% raw %}{{ number_of_shards | default(1) }}{% endraw %}
  },
  "mappings": { ... }
}

{% include copy.html %}

사용 가능한 파라미터 확인하기

워크로드가 지원하는 파라미터를 보려면 info 명령을 사용하세요. 이 명령은 워크로드의 테스트 프로시저와 함께 설정 가능한 파라미터 및 기본값 목록을 보여줘요:

opensearch-benchmark info --workload=geonames

{% include copy.html %}

워크로드 소스를 직접 살펴볼 수도 있어요. 파라미터는 워크로드 JSON 파일에서 {% raw %}{{ variable_name | default(value) }}{% endraw %} 형태로 나타나요. 주요 워크로드 파일은 다음과 같아요:

  • workload.json -- 최상위 워크로드 정의.
  • index.json -- 인덱스 설정과 매핑.
  • test_procedures/default.json -- 테스트 프로시저 스케줄.
  • _operations/default.json -- 연산 정의.

공통 파라미터

다음 파라미터는 대부분의 공식 워크로드에서 지원돼요.

파라미터 설명 기본값
number_of_shards 생성되는 인덱스의 프라이머리 샤드 수. 1
number_of_replicas 생성되는 인덱스의 레플리카 수. 0
bulk_size 벌크 요청당 문서 수. 5000 또는 10000
bulk_indexing_clients 동시 벌크 인덱싱 클라이언트 수. 8
ingest_percentage 수집할 문서 코퍼스의 비율. 100
target_throughput 클라이언트당 초당 목표 연산 수. 제한 없음
search_clients 동시 검색 클라이언트 수. 1
cluster_health 진행 전에 요구되는 클러스터 헬스 상태. green
source_enabled _source 필드 저장 여부. true

벡터 검색 워크로드 파라미터

vectorsearch 워크로드는 벡터 검색 벤치마킹을 위한 추가 파라미터를 지원해요.

파라미터 설명 기본값
target_index_name 벡터 인덱스 이름. target_index
target_field_name 벡터 필드 이름. target_field
target_index_dimension 벡터 차원 수. 768
target_index_space_type 거리 측정 방식. 유효한 값은 l2, innerproduct, cosinesimil이에요. 다양함
target_index_body 인덱스 설정 파일의 경로. indices/faiss-index.json
target_index_bulk_size 벌크 요청당 문서 수. 500
target_index_bulk_index_data_set_format 코퍼스 형식. 유효한 값은 hdf5와 bigann이에요. hdf5
target_index_bulk_index_data_set_corpus 코퍼스 이름(예: cohere-1m). 다양함
target_index_bulk_indexing_clients 동시 인덱싱 클라이언트 수. 10
target_index_max_num_segments force merge 이후의 세그먼트 수. 1
hnsw_ef_construction HNSW 그래프 구축 시 탐색 계수. 256
hnsw_ef_search HNSW 검색 시 탐색 계수. 256
query_k 검색할 최근접 이웃 수. 100
query_count 실행할 쿼리 수. 모든 쿼리를 실행하려면 -1을 사용하세요. -1
query_data_set_format 쿼리 벡터 형식. 유효한 값은 hdf5와 bigann이에요. hdf5
query_data_set_corpus 쿼리 벡터 코퍼스 이름. 다양함
search_clients 동시 검색 클라이언트 수. 1
neighbors_data_set_corpus 재현율 평가에 사용되는 정답(ground-truth) 이웃 코퍼스. 다양함
neighbors_data_set_format 이웃 데이터셋 형식. hdf5

벡터 검색 파라미터 파일 예시

다음 예시는 vectorsearch 워크로드를 위한 완전한 파라미터 파일이에요:

{
  "target_index_name": "vector_1m",
  "target_field_name": "embedding",
  "target_index_body": "indices/faiss-index.json",
  "target_index_primary_shards": 1,
  "target_index_replica_shards": 0,
  "target_index_dimension": 768,
  "target_index_space_type": "innerproduct",
  "target_index_bulk_size": 500,
  "target_index_bulk_index_data_set_format": "hdf5",
  "target_index_bulk_index_data_set_corpus": "cohere-1m",
  "target_index_bulk_indexing_clients": 10,
  "target_index_max_num_segments": 1,
  "hnsw_ef_construction": 200,
  "hnsw_ef_search": 256,
  "query_k": 100,
  "query_data_set_format": "hdf5",
  "query_data_set_corpus": "cohere-1m",
  "query_count": 10000,
  "search_clients": 1,
  "neighbors_data_set_corpus": "cohere-1m",
  "neighbors_data_set_format": "hdf5"
}

{% include copy.html %}

이 파라미터 파일을 사용하려면 params.json으로 저장한 뒤 --workload-params 플래그로 벤치마크를 실행하세요:

opensearch-benchmark run \
  --pipeline=benchmark-only \
  --workload-path=/path/to/vectorsearch \
  --workload-params=params.json \
  --target-hosts=localhost:9200

{% include copy.html %}

더 알아보기 (Learn more)

함께 읽는 실무 이야기

우리 조직에도 적용하고 싶다면, AI 시스템 구축 서비스를 살펴보세요.