로컬 에이전트의 구조화된 출력 오류를 GBNF 문법으로 차단한 사례와 Eris 프로젝트 코드

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

로컬에서 실행되는 에이전트가 JSON 같은 구조화 출력에서 자주 형식 오류를 내는 문제를 해결하기 위해 llama.cpp가 제공하는 GBNF 문법을 활용해 모델이 생성 가능한 토큰을 문법 단계에서 제한하는 접근을 적용했다. 구현은 각 도구의 스키마를 문법 규칙으로 컴파일하는 파이프라인을 포함하며, 턴별로 활성화할 도구 집합을 3~5개로 좁혀 문법 크기와 출력 후보를 함께 제어했다. 이 방식은 닫는 괄호 누락이나 임의 문단 추가 같은 클래스의 오류를 원천적으로 제거하여 로컬 에이전트의 도구 호출 신뢰도를 높였고, Eris라는 Rust 기반의 실제 코드와 저장소 링크로 재현 가능한 예시를 제공한다.

실용적 조언

llama.cpp가 지원하는 GBNF 문법을 활용하여 모델이 생성 가능한 토큰을 문법 수준에서 제한하면 구조화된 출력의 형식 오류를 근본적으로 제거할 수 있다. 구체적으로는 도구의 입력·출력 스키마를 문법 규칙으로 변환해 각 토큰 위치에서 허용 토큰만 남기면 모델은 문법을 벗어나는 토큰을 선택할 수 없다. 이 절차는 로컬 추론 환경에서 특히 유효하며 서버측 보정이 불가능한 상황에서 안전성을 확보하는 방법이다.
다수 도구를 한꺼번에 허용하지 말고 턴별로 관련 도구 집합을 좁혀 적용하면 토큰 탐색 공간을 줄여 잘못된 도구명 생성과 불필요한 서술 출력이 감소한다. 구현 시에는 각 턴의 컨텍스트로 관련 도구 3~5개를 선별해 그에 해당하는 문법만 활성화하면 되며 이렇게 하면 문법 크기와 검증 비용을 동시에 관리할 수 있다. 이 방법은 도구 수가 많은 시스템에서 특히 유용하며 실사용에서 재현 가능한 안정성을 제공한다.
프로젝트 수준에서 재사용 가능한 파이프라인을 구성하려면 도구 스키마를 자동으로 수집·변환하는 컴파일러를 도입하는 것이 유리하다. 스키마를 수동으로 변환하면 실수와 누락이 발생할 소지가 크므로 스키마 정의에서 직접 GBNF 규칙을 생성하는 도구가 필요하며 이는 배포 가능한 로컬 바이너리 형태로 통합할 수 있다. Eris의 구현은 스키마→문법→추론 제약의 파이프라인을 예시로 제공하므로 이를 참조해 초기 구현 비용을 줄일 수 있다.

섹션별 상세

로컬에서 실행되는 에이전트가 JSON 같은 구조화된 출력을 신뢰성 있게 생성하지 못하는 문제가 핵심 문제였다. 요청 시 모델이 중간에 닫는 괄호를 빠뜨리거나 임의의 텍스트를 덧붙이는 등 출력이 규격을 벗어나는 사례가 자주 발생했으며, 호스팅 API는 서버측에서 이를 보정하는 반면 로컬 환경에서는 별도 조치가 필요했다. 해결 접근은 출력 토큰 집합을 문법 규칙으로 제한하는 쪽으로 향했고, 이 글에서는 GBNF 기반으로 토큰 단위를 제어해 잘못된 JSON 생성 자체를 원천적으로 불가능하게 만든 과정을 제시했다.

구체적 구현은 각 도구의 스키마를 받아 이를 GBNF 규칙으로 변환하는 컴파일러를 작성하는 방식으로 진행되었다. 입력으로 도구 스키마가 들어가면 컴파일러는 필드별 허용값과 구조를 토큰 수준의 문법 규칙으로 치환하고, 그 문법을 llama.cpp의 제약 체계에 주입하여 모델의 다음 토큰 생성 후보를 실시간으로 제한한다. 이 방식은 토큰 생성 단계에서 잘못된 구조를 허용하지 않으므로 결과적으로 닫는 괄호 누락이나 임의 문단 삽입 같은 클래스의 오류를 제거한다.

성능 및 실전 적용 측면에서는 문법을 턴별로 좁혀서 적용한 점이 핵심적이었다. 모든 도구를 한꺼번에 허용하는 대신 해당 턴에서 연관 있는 3~5개의 도구만 문법에 포함시키며 이로 인해 모델이 선택할 수 있는 토큰 공간이 크게 줄어들어 잘못된 도구명 생성이나 불필요한 문장 삽입이 줄어들었다는 점이 근거로 제시되었다. 결과적으로 로컬 환경에서 도구 호출 신뢰도가 높아지며, Eris라는 Rust 기반 로컬 에이전트 구현과 함께 코드 저장소와 블로그 글을 통해 직접 재현 가능한 자료가 제공되었다.

용어 해설

GBNF 문법(GBNF): — GBNF는 토큰 단위로 생성 가능한 문자열을 엄격히 제한하는 문법 규칙 형식으로서, 모델이 특정 형식의 출력만 생산하도록 허용 토큰을 제어함으로써 잘못된 JSON과 같은 구조화 출력 오류를 차단한다.
llama.cpp: — llama.cpp는 로컬에서 경량화 모델 추론을 수행하는 런타임으로서 GBNF 같은 문법 제약을 통해 모델이 생성할 수 있는 토큰을 실시간으로 제한하여 출력 형식의 일관성을 확보할 수 있게 한다.
도구 스키마(Tool schema): — 도구 스키마는 각 도구가 받아들이거나 반환하는 필드와 타입을 정의하는 스펙으로서, 이 스키마를 문법 규칙으로 변환하면 에이전트가 호출할 도구 이름과 인수 형식을 토큰 단위로 제한할 수 있다.

언급된 도구

llama.cpp추천

로컬 모델 추론 엔진이자 GBNF 문법 제약을 적용할 수 있는 런타임

Eris중립링크

Markdown 메모리를 사용하는 로컬 퍼스트 에이전트로서 GBNF 기반 출력 제약을 적용한 구현체

Rust중립

Eris의 구현 언어로서 단일 바이너리 배포와 로컬 실행을 용이하게 하는 시스템 언어

언급된 리소스

문서GBNF grammars (Eris 블로그)

GitHubEris GitHub 저장소 (Apache 2.0)