genai_config.json 설정 참조

모델을 제대로 실행하려면 ONNX Runtime GenAI가 설정 파일을 어떻게 읽는지 아는 게 우선이에요. 모델 빌더로 모델을 만들면 genai_config.json 이 자동으로 생성되지만, 직접 준비한 모델이라면 아래 예제를 복사해서 자기 상황에 맞게 고치면 돼요. 설정은 크게 model(모델 구조·파일)과 search(생성·탐색 파라미터) 두 덩어리로 나뉘어요. 이 API는 Preview 단계라서 앞으로 바뀔 수 있다는 점 기억해 두세요.

출처: Config reference (공식 문서)

예제 파일

아래는 decoder-only 방식 모델을 위한 genai_config.json 예시예요.

{
  "model": {
    "bos_token_id": 199999,
    "context_length": 131072,
    "decoder": {
      "session_options": {
        "log_id": "onnxruntime-genai",
        "provider_options": []
      },
      "filename": "model.onnx",
      "head_size": 128,
      "hidden_size": 3072,
      "inputs": {
        "input_ids": "input_ids",
        "attention_mask": "attention_mask",
        "past_key_names": "past_key_values.%d.key",
        "past_value_names": "past_key_values.%d.value"
      },
      "outputs": {
        "logits": "logits",
        "present_key_names": "present.%d.key",
        "present_value_names": "present.%d.value"
      },
      "num_attention_heads": 24,
      "num_hidden_layers": 32,
      "num_key_value_heads": 8
    },
    "eos_token_id": [200020, 199999],
    "pad_token_id": 199999,
    "type": "phi3",
    "vocab_size": 200064
  },
  "search": {
    "diversity_penalty": 0.0,
    "do_sample": false,
    "early_stopping": true,
    "length_penalty": 1.0,
    "max_length": 131072,
    "min_length": 0,
    "no_repeat_ngram_size": 0,
    "num_beams": 1,
    "num_return_sequences": 1,
    "past_present_share_buffer": true,
    "repetition_penalty": 1.0,
    "temperature": 1.0,
    "top_k": 1,
    "top_p": 1.0
  }
}

설정 구조

Config (최상위)

config_path: (string, 내부) 설정 디렉토리의 경로. JSON에는 들어가지 않아요.
model: (object) 모델 구조와 ONNX 모델 설정.
search: (object) 생성·탐색 파라미터.

Config::Model

모델 구조, 파일, 토크나이제이션을 설명해요.

type: (string) 모델 타입. decoder-only LLM의 경우 "decoder"이거나 다음 중 하나예요 — chatglm, gemma, gemma2, gemma3_text, granite, llama, mistral, nemotron, olmo, phi, phimoe, phi3, phi3small, qwen2, qwen3, whisper, marian-ssru, phi3v, phi4mm, gemma3. 여러 모델로 나뉜 decoder-only 모델은 "decoder-pipeline"을 써요.
pad_token_id: (int) 패딩 토큰의 id.
eos_token_id: (int 또는 int 배열) 시퀀스 끝(EOS) 토큰의 id.
bos_token_id: (int) 시퀀스 시작(BOS) 토큰의 id.
sep_token_id: (int, 선택) 구분 토큰의 id.
decoder_start_token_id: (int, 선택) 디코더 시작 토큰 id (encoder-decoder 모델용).
vocab_size: (int) 어휘(vocabulary) 크기.
context_length: (int) 모델이 처리할 수 있는 최대 시퀀스 길이. 입력 토큰(프롬프트)과 출력 토큰(생성 응답)을 모두 포함하며, 이는 모델의 속성이에요.
encoder: (object, 선택) Whisper 같은 모델용. Encoder 참조.
embedding: (object, 선택) 임베딩 서브모듈이 있는 모델용.
vision: (object, 선택) 비전 서브모듈이 있는 모델용.
speech: (object, 선택) 음성 서브모듈이 있는 모델용.
decoder: (object) 디코더 ONNX 모델과 설정. Decoder 참조.

Model::Encoder

filename: (string) 인코더 ONNX 파일 경로.
hidden_size: (int) 인코더의 hidden size.
num_key_value_heads: (int) key-value 헤드 수.
num_hidden_layers: (int) hidden 레이어 수.
head_size: (int) 각 어텐션 헤드 크기.
inputs: (object) input_features, input_ids, attention_mask 텐서 이름.
outputs: (object) encoder_outputs 텐서 이름.

Model::Vision

filename: (string) 비전 ONNX 파일 경로.
config_filename: (string, 선택) 비전 프로세서 설정 파일 경로.
adapter_filename: (string, 선택) 비전 어댑터 파일 경로.
inputs: (object) pixel_values, image_sizes, attention_mask 텐서 이름.
outputs: (object) image_features 출력 텐서 이름.

Model::Speech

filename: (string) 음성 ONNX 파일 경로.
config_filename: (string, 선택) 음성 프로세서 설정 파일 경로.
adapter_filename: (string, 선택) 음성 어댑터 파일 경로.
inputs: (object) audio_embeds, attention_mask, audio_sizes, audio_projection_mode 텐서 이름.
outputs: (object) audio_features 출력 텐서 이름.

Model::Decoder

filename: (string) 디코더 ONNX 파일 경로.
session_options: (object) SessionOptions 참조.
hidden_size: (int) hidden 레이어 크기.
num_attention_heads: (int) 어텐션 헤드 수.
num_key_value_heads: (int) key-value 헤드 수.
num_hidden_layers: (int) hidden 레이어 수.
head_size: (int) 각 어텐션 헤드 크기.
sliding_window: (object, 선택) 슬라이딩 윈도우 추론 파라미터 — window_size, pad_value, alignment("left"/"right"), slide_key_value_cache.
inputs: (object) input_ids, embeddings, position_ids, attention_mask, past_key_names, past_value_names, past_names(선택), cross_past_key_names(선택), cross_past_value_names(선택), current_sequence_length, past_sequence_length, past_key_values_length, total_sequence_length, encoder_hidden_states, rnn_prev_states(선택), encoder_attention_mask(선택) 텐서 이름.
outputs: (object) logits, present_key_names, present_value_names, present_names(선택), cross_present_key_names(선택), cross_present_value_names(선택), rnn_states(선택) 텐서 이름.
pipeline: (array, 선택) 파이프라인 모델용으로, 각각의 파일명·session options·inputs·outputs를 가진 서브모델 목록.

Model::Decoder::PipelineModel

model_id: (string) 파이프라인 모델 식별자.
filename: (string) ONNX 파일 경로.
session_options: (object, 선택) 이 파이프라인 모델의 session options.
inputs: (array of string) 입력 텐서 이름 목록.
outputs: (array of string) 출력 텐서 이름 목록.
output_names_forwarder: (object) 전달할 출력 이름 매핑.
run_on_prompt: (bool) 프롬프트에서 이 모델을 실행할지.
run_on_token_gen: (bool) 토큰 생성 중 이 모델을 실행할지.
reset_session_idx: (int) 메모리 관리를 위해 리셋할 세션의 인덱스.

SessionOptions

모델 실행을 위해 ONNX Runtime에 전달하는 옵션이에요.

intra_op_num_threads: (int, 선택) intra-op 병렬화 스레드 수.
inter_op_num_threads: (int, 선택) inter-op 병렬화 스레드 수.
enable_cpu_mem_arena: (bool, 선택) CPU 메모리 아레나 enable/disable.
enable_mem_pattern: (bool, 선택) 메모리 패턴 최적화 enable/disable.
disable_cpu_ep_fallback: (bool, 선택) CPU 실행 프로바이더 폴백 비활성화.
disable_quant_qdq: (bool, 선택) 양자화 QDQ 비활성화.
enable_quant_qdq_cleanup: (bool, 선택) 양자화 QDQ 정리 활성화.
ep_context_enable: (bool, 선택) 실행 프로바이더 컨텍스트 활성화.
ep_context_embed_mode: (string, 선택) 실행 프로바이더 컨텍스트 embed 모드.
ep_context_file_path: (string, 선택) 실행 프로바이더 컨텍스트 파일 경로.
log_id: (string, 선택) 로깅 접두사.
log_severity_level: (int, 선택) 로깅 심각도 수준.
enable_profiling: (string, 선택) 프로파일링 활성화.
custom_ops_library: (string, 선택) 커스텀 ops 라이브러리 경로.
use_env_allocators: (bool) 환경 할당자 사용 여부.
config_entries: (array of [string, string] 쌍) 추가 설정 항목.
provider_options: (array of ProviderOptions) 실행 프로바이더 옵션 목록.
providers: (array of string) 런타임에 사용할 프로바이더 목록.
graph_optimization_level: (string, 선택) 그래프 최적화 수준.

ProviderOptions

name: (string) 프로바이더 이름. 지정하지 않으면 CPU로 기본 설정돼요 — cuda, DML, NvTensorRtRtx, OpenVINO, QNN, WebGPU, VitisAI.
options: (array of [string, string] 쌍) 프로바이더별 옵션.

Search

생성·탐색 파라미터를 설명해요.

do_sample: (bool) 무작위 샘플링(top-k/top-p)을 쓸지, 결정적(greedy) 탐색을 쓸지.
min_length: (int) 프롬프트 + 생성 시퀀스의 최소 길이. 0에서 모델 context length 사이.
max_length: (int) 프롬프트 + 생성 시퀀스의 최대 길이. 0에서 모델 context length 사이. 설정이나 사용자가 지정하지 않으면 모델의 context length로 정해져요. max_length가 KV cache에 할당할 메모리 크기를 결정해요.
batch_size: (int) 병렬로 생성할 시퀀스 수.
num_beams: (int) beam search의 beam 수. 1이면 beam search를 쓰지 않아요.
num_return_sequences: (int) 반환할 시퀀스 수.
repetition_penalty: (float) 토큰 반복 페널티. 1.0이면 페널티 없음.
top_k: (int) Top-K 샘플링 파라미터.
top_p: (float) Top-P(nucleus) 샘플링 파라미터.
temperature: (float) 샘플링 온도.
early_stopping: (bool) beam search를 일찍 멈출지 여부.
no_repeat_ngram_size: (int) 반복하지 않아야 할 n-gram 크기.
diversity_penalty: (float) 현재는 지원되지 않아요.
length_penalty: (float) 출력 길이를 조절해요. 1.0보다 크면 더 긴 시퀀스를, 작으면 더 짧은 시퀀스를 장려해요.
past_present_share_buffer: (bool) true면 효율을 위해 past와 present 버퍼를 공유해요. 자세한 설명은 past present share buffer를 참고하세요.
random_seed: (int) 난수 생성기 시드. -1이면 랜덤 디바이스를 사용해요.

참고 사항

session_options: 스레딩, 메모리 아레나, 양자화, 프로파일링, 커스텀 ops 같은 고급 ONNX Runtime 옵션을 지원해요. 실제 가능한 모든 필드는 C++ SessionOptions 구조체를 참고하세요.
inputs/outputs: 여기 있는 이름과 패턴은 실제 ONNX 모델 그래프와 일치해야 해요.
pipeline: 고급 모델은 각각 고유한 ONNX 파일·session options·input/output 매핑을 가진 서브모델의 파이프라인으로 지정할 수 있어요.

탐색 조합 정리

Beam search: num_beams > 1, do_sample = false, past_present_share_buffer = false
Greedy search: num_beams = 1, do_sample = false
Top P / Top K 무작위 샘플링: do_sample = true

genai_config.json 설정 참조

genai_config.json 설정 참조

예제 파일

설정 구조

Config (최상위)

Config::Model

Model::Encoder

Model::Vision

Model::Speech

Model::Decoder

Model::Decoder::PipelineModel

SessionOptions

ProviderOptions

Search

참고 사항

탐색 조합 정리

더 알아보기