언어 바이어스¶

목차¶

• 언어 바이어스란?
• 빠른 시작
• 플래그 참조
• YAML 설정 스키마
• 포함 정책
• 예외 플래그
• 캐시
• 관찰 가능성
• 제한 사항
• 사용 사례 예시
• 문제 해결

언어 바이어스란?¶

언어 바이어스는 mlxcel이 어휘 수준에서 출력 분포를 직접 조작하는 메커니즘입니다. 후처리 필터나 활성화 수준 조향과 달리, 토큰 샘플링 과정에서 언어 모델이 생성한 로짓(logit)에 직접 개입합니다. 온도 스케일링이나 반복 페널티가 적용되기 전에, 특정 언어에 속하는 모든 토큰의 원시 로짓에 가산 바이어스를 적용합니다. -inf로 바이어스된 토큰은 확률 분포에서 완전히 제거됩니다(소프트맥스 가중치가 정확히 0이 됨). 양수 바이어스를 부여받은 토큰은 더 높은 확률로 선택됩니다. 이 처리는 샘플링 커널 내부에서 이루어지므로, 정책이 없을 때는 오버헤드가 전혀 없고 정책이 설정된 경우에도 벡터 덧셈 비용만 발생합니다.

프리셋 레이어는 사람이 읽을 수 있는 언어 코드를 실제 어휘 토큰 집합으로 매핑합니다. 첫 실행 시 토크나이저의 전체 어휘를 스캔해 각 토큰을 유니코드 스크립트 속성에 따라 분류하고 결과를 디스크에 캐시하므로 이후 실행에서는 스캔을 건너뜁니다. Conservative와 Strict 두 가지 분류 정책을 통해, 예를 들어 한자를 포함한 한국어처럼 복합 스크립트 토큰을 어느 범위에서 각 언어의 정의에 포함시킬지 조정할 수 있습니다.

빠른 시작¶

한 언어는 억제하고 다른 언어는 증폭 (권장)¶

실제 쓸만한 사용 패턴은 피해야 할 언어와 선호할 언어를 같이 지정하는 방식입니다. 억제만 걸면 분포가 허용 범위 (숫자, 공백, 구두점) 로 밀리는데 그 범위만으로는 의미있는 응답이 안 나오는 경우가 많고 선호 언어에 양의 바이어스를 함께 주면 모델이 그쪽으로 수렴할 수 있습니다.

mlxcel generate \
  --model ./models/Qwen2.5-7B-Instruct-4bit \
  --prompt "日本の首都は" \
  --lang-bias ja=-inf,zh=-inf,ko=+5 \
  --max-tokens 100

qwen2.5-0.5b-bf16에서 실제 확인한 결과: 바이어스 없이는 일본어로 이어지는데 (日本の首都は東京都です), 위 설정을 주면 자연스러운 한국어 (답변하신 내용은 한국의 수도 서울입니다. 서울은 대한민국의 수도로 인해 세계적으로 유명한 대학과 연구...) 로 전환됩니다. 증폭 바이어스는 +5에서 +10 사이가 무난한 출발점이고 +20 이상이면 특정 토큰이 분포를 너무 강하게 장악해서 반복 출력이 늘어나는 편입니다.

억제만 적용 (가드레일 용도)¶

문장이 불완전하더라도 특정 언어만은 반드시 차단해야 할 때 쓰는 패턴입니다.

mlxcel generate \
  --model ./models/Qwen2.5-7B-Instruct-4bit \
  --prompt "今日のニュースを教えてください。" \
  --lang-bias ja=-inf,zh=-inf \
  --max-tokens 100

프롬프트의 자연스러운 연결이 억제된 언어였다면 출력이 숫자나 구두점 위주로 나올 수 있는데 이는 모델이 분포에서 억제되지 않은 꼬리 부분만 남은 상태에서 여전히 샘플링을 하기 때문입니다.

서버에 전역 바이어스 적용¶

mlxcel serve \
  --model ./models/Qwen2.5-7B-Instruct-4bit \
  --lang-bias ja=-inf,zh=-inf,ko=+5 \
  --port 8080

플래그 참조¶

--lang-bias <항목>¶

언어 토큰 집합에 가산 로짓 바이어스를 적용합니다.

구문:

--lang-bias <항목>[,<항목>]*
<항목>  = <언어코드>=<바이어스값>
<바이어스값>   = -inf | +inf | inf | <float>
<언어코드> = ja | zh | ko | en | ru | ar | th | hi | he | el

기본값: 없음 (바이어스 미적용).

예시:

--lang-bias ja=-inf,zh=-inf
--lang-bias ko=+5.0
--lang-bias en=+3,ja=-inf,zh=-5.5

동일한 항목 집합에서 언어 코드가 중복되면 파싱 오류가 발생합니다. 바이어스 값은 32비트 부동소수점으로 파싱되며 -inf와 +inf는 리터럴로 허용됩니다.

--lang-bias-config <경로>¶

인라인 플래그 대신 YAML 파일에서 언어 바이어스 설정을 로드합니다. 전체 형식은 YAML 설정 스키마 섹션을 참조하십시오.

기본값: 없음.

예시:

mlxcel generate \
  --model ./models/Qwen2.5-7B-Instruct-4bit \
  --prompt "Hello" \
  --lang-bias-config ./lang-policy.yaml

YAML 파일에는 정책, 바이어스 항목, 예외 설정을 함께 지정할 수 있습니다. --lang-bias와 --lang-bias-config를 동시에 지정하면 병합되며 동일 언어에 대해서는 인라인 --lang-bias 항목이 우선합니다.

--lang-bias-policy {conservative|strict}¶

모든 언어 집합에 적용할 토큰 포함 정책을 설정합니다.

기본값: conservative.

값:

예시:

mlxcel generate \
  --model ./models/Qwen2.5-7B-Instruct-4bit \
  --prompt "한국어 시험 문제" \
  --lang-bias ko=-inf \
  --lang-bias-policy strict

--lang-bias-include-special¶

토크나이저의 특수 토큰(BOS, EOS, PAD, UNK, 템플릿 구분자)을 스크립트 분류에 포함합니다. 기본적으로 이 토큰들은 모든 언어 집합에서 제외되어, 언어를 억제해도 시퀀스 종료 생성이 차단되지 않습니다.

기본값: 꺼짐 (특수 토큰 제외).

--lang-bias-include-numeric¶

순수 숫자 토큰을 스크립트 분류에 포함합니다. 기본적으로 0-9 시퀀스와 유니코드 숫자 문자는 제외됩니다.

기본값: 꺼짐.

--lang-bias-include-punctuation¶

순수 구두점 토큰을 스크립트 분류에 포함합니다.

기본값: 꺼짐.

--lang-bias-include-byte-fragments¶

UTF-8 시작 바이트 분석을 통해 byte-fragment 토큰을 스크립트 분류에 포함합니다.

Qwen, GPT-2, LLaMA, Mistral 같은 byte-level BPE 토크나이저는 덜 흔한 CJK 글자를 개별 byte 토큰 시퀀스로 표현하는데 각 byte를 단독으로 decode하면 U+FFFD가 되어 기본 분류기에서는 Other로 분류됩니다. 그래서 ja=-inf, zh=-inf 필터가 이들을 놓치고 생성 시 byte 조각들이 다시 조립되어 억제 대상 글자가 출력에 나타날 수 있습니다.

이 플래그를 켜면 어휘 스캔에서 byte-fragment 토큰을 원본 바이트로 역매핑하고 UTF-8 시작 바이트 범위에 따라 가능성 높은 스크립트를 태그합니다 (0xE3 → 히라가나, 0xE4-0xE9 → 한자, 0xEA-0xED → 한글, 0xF0-0xF4 → 보조 평면 한자). 연속 바이트 (0x80-0xBF) 는 스크립트 간에 모호해서 Other로 남습니다.

시작 바이트 분류는 근사치이기 때문에 완벽하지 않습니다. 0xE4-0xE9 범위는 대부분의 CJK 통합 한자를 잡지만 Latin Extended Additional의 일부도 함께 포함되어서 플래그를 켜면 무관한 토큰이 일부 과도하게 억제될 수 있습니다. 운영 환경에서는 /metrics의 mlxcel_lang_bias_byte_fragment_suppressions_total 카운터로 byte-fragment 경로에서 발생하는 억제량을 관찰하고 출력에 과도한 억제가 보이면 플래그를 끌 수 있습니다.

기본값: 꺼짐. 꺼져 있을 때는 byte-fragment 토큰을 스크립트 분류에서 제외합니다.

예시:

mlxcel generate \
  --model ./models/Qwen2.5-7B-Instruct-4bit \
  --prompt "日本の首都は" \
  --lang-bias ja=-inf,zh=-inf,ko=+5 \
  --lang-bias-include-byte-fragments \
  --max-tokens 100

이 플래그를 켜면 아래 '제한 사항'에서 설명하는 Qwen2.5의 [74577, 112] 토큰화 (공백+年) 에서 앞쪽 byte-fragment가 한자로 태그되어 zh=-inf에 걸립니다.

--lang-bias-rebuild-cache¶

현재 모델 토크나이저의 TokenLanguageIndex 캐시를 강제로 재구성합니다. 기존 캐시 파일을 삭제하고 새로운 파일을 씁니다. 어휘가 변경되면 캐시가 자동으로 무효화되므로 이 플래그는 거의 필요하지 않습니다.

기본값: 꺼짐.

LLAMA_ARG_LANG_BIAS (환경 변수)¶

--lang-bias와 동일한 구문을 환경 변수로 읽습니다. 프로세스 매니저나 컨테이너 오케스트레이션 시스템에서 LLAMA_ARG_* 변수를 설정하여 mlxcel-server를 실행할 때 사용합니다. 명령줄 플래그가 이 환경 변수보다 항상 우선합니다.

예시:

export LLAMA_ARG_LANG_BIAS="ja=-inf,zh=-inf"
mlxcel serve --model ./models/Qwen2.5-7B-Instruct-4bit

LLAMA_ARG_LANG_BIAS_INCLUDE_BYTE_FRAGMENTS (환경 변수)¶

byte-fragment 분류기를 환경 변수로 활성화합니다. 값은 true/false/1/0/yes/no/on/off (대소문자 구분 없음) 를 받습니다. 파싱 불가능한 값은 로그에 기록하고 무시되며 파싱 오류를 내지 않습니다. 명령줄의 --lang-bias-include-byte-fragments가 이 환경 변수보다 우선합니다.

예시:

export LLAMA_ARG_LANG_BIAS="ja=-inf,zh=-inf,ko=+5"
export LLAMA_ARG_LANG_BIAS_INCLUDE_BYTE_FRAGMENTS=true
mlxcel serve --model ./models/Qwen2.5-7B-Instruct-4bit

YAML 설정 스키마¶

--lang-bias-config로 전달하는 YAML 설정 파일은 세 개의 최상위 키를 가집니다:

# 포함 정책: conservative (기본값) 또는 strict
policy: conservative

# 언어별 로짓 바이어스. -inf, +inf, 임의의 부동소수점 허용.
bias:
  ja: -inf
  zh: -10.0
  ko: +5.0

# 예외 설정. 모두 기본값은 false.
exceptions:
  include_special: false
  include_numeric: false
  include_punctuation: false
  include_byte_fragments: false

모든 키는 선택 사항입니다. 빈 파일도 유효하며 바이어스를 적용하지 않습니다.

포함 정책¶

포함 정책은 여러 스크립트의 문자를 포함하는 토큰을 언어 집합에 할당하는 방식을 제어합니다.

Conservative vs Strict 매트릭스¶

대부분의 언어에서 Conservative와 Strict는 동일합니다. 한국어가 주목할 만한 예외입니다.

동작 예시: 한국어¶

현대 한국어 텍스트는 한글 음절과 한자로 표기되는 한자어(漢字語)를 혼용합니다. 이로 인해 두 정책 간에 의미 있는 차이가 발생합니다:

Conservative (--lang-bias-policy conservative, 기본값):

• 한국어 집합 = 한글 또는 한자 문자를 포함하는 토큰.
• --lang-bias ko=-inf를 적용하면 한글 토큰과 독립적인 한자 토큰 모두가 억제됩니다.
• 한국어 출력을 가장 완전하게 억제하지만 일본어와 중국어 어휘와 공유되는 한자 토큰도 제거됩니다.

Strict (--lang-bias-policy strict):

• 한국어 집합 = 모든 문자가 한글인 토큰만 포함.
• --lang-bias ko=-inf를 적용하면 순수 한글 토큰만 억제됩니다. 한자 토큰은 영향을 받지 않습니다.
• 일본어나 중국어 어휘에서 사용하는 한자 토큰은 한국어가 억제된 상태에서도 사용 가능합니다.

정책 선택 기준:

• 한국어 출력을 완전히 차단하고 한자 출력이 불필요한 경우: Conservative 사용.
• 한국어를 억제하면서 CJK 공유 문자(예: 일본어나 중국어와 함께 사용하는 한자)는 유지해야 하는 경우: Strict 사용.

예외 플래그¶

포함 정책에 관계없이, 다음 세 가지 범주의 토큰은 기본적으로 모든 언어 집합에서 제외됩니다:

공백 전용 토큰은 항상 제외되며 재정의할 수 없습니다.

예외 플래그 사용 시기:

• --lang-bias-include-special: 거의 필요하지 않습니다. 모델이 텍스트 종료나 패드 토큰을 명시적으로 생성하지 못하도록 방지하려는 경우에만 해당됩니다. 언어를 억제할 때 이 플래그를 활성화하면 모델이 EOS를 생성할 수 없어 생성이 멈출 수 있습니다.
• --lang-bias-include-numeric: 특정 스크립트와 관련된 숫자 시퀀스(예: 아랍 숫자를 억제할 때의 아랍-인도 숫자)를 포함하여 해당 언어의 모든 토큰을 억제하려는 경우에 유용합니다. 고유한 숫자 문자가 없는 스크립트에는 영향이 없습니다.
• --lang-bias-include-punctuation: 대상 스크립트에 고유한 구두점 문자가 있는 경우에 유용합니다(예: 일본어 괄호 「」 또는 한국어 인용 부호). 이 플래그를 사용하지 않으면 해당 구두점 토큰은 언어가 억제되더라도 사용 가능한 상태로 유지됩니다.

캐시¶

위치¶

${MLXCEL_CACHE_DIR:-$HOME/.cache/mlxcel}/tokenizer-scripts/<vocab_hash>.bin

MLXCEL_CACHE_DIR이 빈 값이면 설정하지 않은 것으로 취급합니다.

<vocab_hash>는 tokenizer.json 바이트의 SHA-256 다이제스트 앞 16자리 16진수입니다. 파일은 postcard로 직렬화되며 해당 어휘에 대한 전체 TokenLanguageIndex를 포함합니다.

자동 무효화¶

캐시는 다음 경우에 자동으로 재구성됩니다:

• 캐시 파일이 없는 경우 (해당 토크나이저로 처음 실행).
• 캐시 파일의 스키마 버전이 현재 mlxcel 버전과 일치하지 않는 경우.
• 캐시 파일을 읽을 수 없는 경우 (잘린 파일 또는 손상). 재구성 전에 기존 파일이 <경로>.broken.<epoch>.bak으로 이름이 변경됩니다.

수동 재구성¶

mlxcel generate \
  --model ./models/Qwen2.5-7B-Instruct-4bit \
  --lang-bias-rebuild-cache \
  --prompt "Hello" \
  --max-tokens 1

서버 사용 시:

mlxcel serve \
  --model ./models/Qwen2.5-7B-Instruct-4bit \
  --lang-bias-rebuild-cache

--lang-bias-rebuild-cache 플래그는 바이어스가 설정되어 있지 않아도 작동합니다. 인덱스를 재구성하고 이후 실행을 위해 캐시에 저장합니다.

관찰 가능성¶

mlxcel-server 사용 시 /metrics 엔드포인트 (Prometheus 형식) 에서 언어 바이어스 활동을 모니터링하는 세 개의 카운터를 제공합니다:

예시:

curl -s http://localhost:8080/metrics | grep lang_bias

바이어스가 활성화된 경우 예상 출력:

# HELP mlxcel_lang_bias_applied_total Sampling steps with a non-empty language bias map applied
# TYPE mlxcel_lang_bias_applied_total counter
mlxcel_lang_bias_applied_total 1482
# HELP mlxcel_lang_bias_tokens_suppressed_total Sampling steps where the top-1 candidate was suppressed by -inf bias
# TYPE mlxcel_lang_bias_tokens_suppressed_total counter
mlxcel_lang_bias_tokens_suppressed_total 374
# HELP mlxcel_lang_bias_byte_fragment_suppressions_total Suppressions where the neg-inf top-1 token was classified via UTF-8 start-byte
# TYPE mlxcel_lang_bias_byte_fragment_suppressions_total counter
mlxcel_lang_bias_byte_fragment_suppressions_total 41

트레이싱 필드 (RUST_LOG=debug 또는 분산 트레이싱 백엔드에서 확인 가능):

• lang_bias.entries: 활성 바이어스 항목 수
• lang_bias.byte_fragment_entries: byte-fragment 항목 수 (0이 아닐 때만 표시)
• lang_bias.languages: 바이어스가 적용된 언어 코드 목록 (쉼표 구분)
• lang_bias.policy: conservative 또는 strict

제한 사항¶

서빙 인스턴스당 단일 전역 정책. 언어 바이어스 설정은 하나의 mlxcel-server 인스턴스가 처리하는 모든 요청에 적용됩니다. OpenAI 호환 API에서는 요청별 재정의를 지원하지 않습니다.

10개 언어 지원. 언어 바이어스는 현재 ja, zh, ko, en, ru, ar, th, hi, he, el을 지원합니다. 새로운 언어 추가에는 토크나이저 검증이 필요합니다.

Script::Other 토큰은 분류되지 않음. 10개 언어 집합에서 다루지 않는 유니코드 스크립트(예: 조지아어, 아르메니아어, 수학 기호)에 속하는 문자를 포함하는 토큰은 Script::Other로 분류되며 어떤 언어 집합에도 포함되지 않습니다. 언어 바이어스의 영향을 받지 않습니다.

배치 내 시퀀스별 차별화 미지원. 하나의 배치에서 여러 시퀀스를 처리할 때 모든 시퀀스가 동일한 언어 바이어스 정책을 사용합니다. 단일 서빙 인스턴스 내에서 동시 요청에 서로 다른 언어 정책을 적용하려면 요청별 재정의 기능이 필요합니다.

Byte-level BPE 토크나이저의 CJK 문자 우회. Qwen, GPT-2, LLaMA, Mistral 같은 byte-level BPE 토크나이저는 덜 흔한 CJK 글자를 단일 merged 토큰이 아니라 개별 byte 토큰들의 시퀀스로 표현합니다. 기본 분류기에서는 각 byte를 단독으로 decode하면 U+FFFD가 되어 Other로 분류되고 그래서 ja=-inf, zh=-inf 필터에 걸리지 않은 채 byte 조각들이 생성 시 다시 조립되어 억제 대상 글자가 출력에 나타납니다.

opt-in 플래그 --lang-bias-include-byte-fragments(및 같은 역할의 환경변수 LLAMA_ARG_LANG_BIAS_INCLUDE_BYTE_FRAGMENTS)는 이 문제를 상당 부분 해소합니다. 플래그를 켜면 어휘 스캔에서 byte-fragment 토큰을 원본 바이트로 역매핑하고 UTF-8 시작 바이트 범위에 따라 가능성 높은 스크립트를 태그합니다. Qwen2.5-0.5b 기준의 구체적인 확인 예: 年이 단독으로 나올 때는 토큰이 하나 (7948, decode 결과 年, Han 분류, 두 모드 모두에서 바이어스 적용됨). 같은 글자 앞에 공백이 붙으면 byte 조각 두 개 (74577, 112)로 쪼개지는데 플래그를 끈 상태에서는 두 조각 모두 Other로 남아 zh=-inf를 통과하고 플래그를 켠 상태에서는 앞 조각 74577이 시작 바이트 범위를 통해 한자로 태그되어 억제가 적용됩니다.

byte-fragment 경로가 완전 차단은 아닙니다. 연속 바이트 (0x80-0xBF) 는 스크립트 간에 모호해서 여전히 Other로 남기 때문에, 시작 바이트는 억제되었지만 연속 바이트가 다른 언어 집합을 통해 빠져나가는 경계 사례에서는 억제 대상 CJK 글자가 출력에 섞여 나올 수 있습니다. 시작 바이트 분류 자체도 근사치여서 0xE4-0xE9 범위는 대부분의 CJK 통합 한자를 잡지만 Latin Extended Additional의 일부도 함께 포함하므로, 플래그를 켜면 무관한 토큰이 일부 과도하게 억제될 수 있습니다. 운영 환경에서는 mlxcel_lang_bias_byte_fragment_suppressions_total 카운터로 byte-fragment 경로에서 발생하는 억제량을 관찰하고 비율이 지나치게 높으면 플래그를 되돌릴 수 있습니다. 결합된 필터도 여전히 완전 차단이 아니라 더 강한 선호로 이해하십시오.

사용 사례 예시¶

예시 1: 한국어 전용 서비스 (Conservative)¶

일본어나 중국어 출력이 허용되지 않는 한국어 고객 지원 서비스:

mlxcel serve \
  --model ./models/Qwen2.5-7B-Instruct-4bit \
  --lang-bias ja=-inf,zh=-inf \
  --lang-bias-policy conservative \
  --port 8080

Conservative 정책을 사용하면 히라가나, 가타카나, 한자 스크립트 토큰이 모두 분포에서 제거됩니다. 모델의 한글 어휘와 고유명사 및 기술 용어를 위한 라틴 스크립트 토큰은 유지됩니다.

예시 2: 한자를 보존하는 한국어 전용 서비스¶

한자(한국어 맥락에서 사용되는 한자)는 출력할 수 있되, 일본어 가나는 출력하면 안 되는 한국어 서비스:

mlxcel serve \
  --model ./models/Qwen2.5-7B-Instruct-4bit \
  --lang-bias ja=-inf \
  --lang-bias-policy strict \
  --port 8080

Strict 정책을 사용하면 ja=-inf는 모든 문자가 히라가나 또는 가타카나(또는 가나+한자 혼합)인 토큰만 억제합니다. 순수 한자 토큰은 ja strict 집합에 포함되지 않아 사용 가능한 상태로 유지됩니다. 이를 통해 일본어 가나 출력을 차단하면서 한자어 어휘는 보존할 수 있습니다.

또는 한국어 한글 자체를 억제하면서 한자는 유지하는 경우(테스트나 마이그레이션 시나리오):

mlxcel generate \
  --model ./models/Qwen2.5-7B-Instruct-4bit \
  --prompt "한국어 시험 문제" \
  --lang-bias ko=-inf \
  --lang-bias-policy strict \
  --max-tokens 50

예시 3: 영어 시험 서비스 (비라틴 스크립트 억제)¶

모든 출력이 라틴 스크립트 문자만 사용해야 하는 영어 시험 플랫폼:

mlxcel serve \
  --model ./models/Qwen2.5-7B-Instruct-4bit \
  --lang-bias ja=-inf,zh=-inf,ko=-inf,ru=-inf,ar=-inf,th=-inf,hi=-inf,he=-inf,el=-inf \
  --lang-bias-policy conservative \
  --port 8080

이 설정은 9개의 비라틴 언어 집합을 모두 분포에서 제거하고 라틴 스크립트 출력, 숫자 토큰, 구두점, 특수 토큰만 남깁니다.

동일한 설정을 YAML 파일로 구성하는 방법:

# exam-english-only.yaml
policy: conservative
bias:
  ja: -inf
  zh: -inf
  ko: -inf
  ru: -inf
  ar: -inf
  th: -inf
  hi: -inf
  he: -inf
  el: -inf

mlxcel serve \
  --model ./models/Qwen2.5-7B-Instruct-4bit \
  --lang-bias-config ./exam-english-only.yaml \
  --port 8080

문제 해결¶

바이어스가 효과 없음¶

--lang-bias를 추가해도 모델 출력이 변경되지 않는 경우.

1. 플래그 문법을 확인하십시오. mlxcel generate --help를 실행하여 정확한 플래그 이름을 확인하십시오. 일부 셸 설정에서는 오타가 있는 경우 인식되지 않는 플래그로 조용히 통과될 수 있습니다.
2. 억제하려는 언어가 실제로 이 모델의 어휘에 있는지 확인하십시오. 모든 모델이 동일한 다국어 커버리지를 갖지는 않습니다. 주로 영어로 학습된 모델은 일본어 토큰이 매우 적을 수 있으며 억제해도 이미 영어였던 출력에는 눈에 띄는 효과가 없습니다.
3. 지표 카운터를 확인하십시오. mlxcel-server 사용 시 curl /metrics | grep lang_bias_applied_total이 0이 아닌 값을 보여야 합니다. 0이면 바이어스 맵이 비어 있다는 의미입니다(토크나이저 스캔에서 지정된 언어에 대한 토큰이 생성되지 않음).
4. 캐시를 재구성하십시오. --lang-bias-rebuild-cache 플래그를 사용하여 어휘 스캔을 강제로 새로 실행하십시오.
5. applied 카운터는 증가했는데 억제 대상 언어 글자가 일부 나옵니다. '제한 사항'에서 설명한 byte-fragment CJK 우회 현상입니다. 기본 설정에서는 byte-fragment 토큰이 Other로 남아 필터를 통과하고 생성 시 다시 조립되는데 두 가지 대응이 가능합니다:
6. --lang-bias-include-byte-fragments 를 켜거나 LLAMA_ARG_LANG_BIAS_INCLUDE_BYTE_FRAGMENTS=true 를 설정합니다. UTF-8 시작 바이트 분석으로 byte-fragment 토큰에 스크립트를 태그해서 우회의 대부분을 잡아냅니다. /metrics의 mlxcel_lang_bias_byte_fragment_suppressions_total 카운터로 실제 억제 발생 여부를 확인하고 출력에서 과도한 억제 (예: 관련 없는 Latin Extended 토큰들이 사라짐) 가 보이면 플래그를 되돌립니다.
7. 억제와 함께 대체 언어의 promote 바이어스 (예: ja=-inf,zh=-inf,ko=+5) 를 줘서 모델이 우회 경로 쪽으로 가지 않게 유도합니다. byte-fragment 플래그 없이도 분포를 우회 경로를 타지 않는 토큰 쪽으로 당겨주기 때문에 도움이 됩니다.

출력 품질 저하¶

--lang-bias를 추가한 후 모델이 일관성 없는 출력, 반복, 또는 매우 짧은 응답을 생성하는 경우.

1. 강도를 낮추십시오. -inf를 -10.0과 같은 큰 음수 부동소수점으로 변경하십시오. 강한 억제(-inf)는 토큰을 분포에서 완전히 제거합니다. 모델이 문법 구조를 위해 해당 토큰에 의존한다면 품질이 급격히 저하됩니다.
2. Strict 정책으로 전환하십시오. Conservative 정책이 예상보다 더 많은 토큰을 억제하고 있을 수 있습니다(예: 모델이 구조적 목적으로도 사용하는 한자 스크립트 토큰). --lang-bias-policy strict를 추가하면 억제 집합이 좁아집니다.
3. 구두점 재활성화. 일부 구두점 토큰은 스크립트와 연관되어 있습니다(예: 일본어 전각 구두점). --lang-bias-include-punctuation을 추가하면 해당 토큰이 사용 가능한 집합으로 돌아옵니다.
4. 의도하지 않은 EOS 억제 확인. 억제된 언어 집합에 EOS 토큰이 포함된 경우(사용자 정의 어휘에서는 가능하나 가능성이 낮음), --lang-bias-include-special을 추가하여 확인하고 EOS가 억제된 집합에 있는지 점검하십시오.

캐시 재구성 실패¶

mlxcel이 캐시 파일 읽기 또는 쓰기 오류를 보고하는 경우.

1. 디스크 공간을 확인하십시오. 캐시 디렉터리는 ${MLXCEL_CACHE_DIR:-$HOME/.cache/mlxcel}/tokenizer-scripts/입니다. 대형 어휘(150k+ 토큰)는 몇 메가바이트가 필요할 수 있습니다.
2. 손상된 파일을 수동으로 삭제하십시오. 오류 메시지에 표시된 경로의 파일을 찾아 제거하십시오:

   ls ~/.cache/mlxcel/tokenizer-scripts/
   trash-put ~/.cache/mlxcel/tokenizer-scripts/<vocab_hash>.bin
   

   그런 다음 --lang-bias-rebuild-cache로 재실행하십시오.
3. 쓰기 가능한 위치로 MLXCEL_CACHE_DIR을 설정하십시오. 기본 캐시 경로가 읽기 전용 파일 시스템인 경우:

   export MLXCEL_CACHE_DIR=/tmp/mlxcel-cache
   mlxcel generate --model ./models/... --lang-bias ko=-inf --prompt "Hello" --max-tokens 5