3주 전, 저는 지식 기반 문서 어시스턴트를 위한 오픈 표준 구축 글을 게재했습니다.

당시 Grounded LLM은 v0.1.0이었으며, 명세(spec), 적합성 CLI, 하이브리드 검색(hybrid retrieval), 그리고 CI에서 89개의 평가 케이스를 갖춘 신뢰할 수 있는 레퍼런스 구현체였습니다.

솔직히 말하자면: 그것은 올바른 '이야기'였지만. 여전히 아이디어의 매우 좋은 v1처럼 느껴졌습니다.

그 이후로 저는 v0.2.0(프로덕션 강화)을 출시했고, 이번 주에는 **v0.3.0**을 출시했습니다.

이 글은 변경 로그 나열이 아닙니다. 이것은 구축하는 동안 제 머릿속에서 바뀐 것, 그리고 왜 기업 RAG(Retrieval-Augmented Generation)가 또 다른 데모 GIF가 아니라 이런 다이어그램을 필요로 한다고 생각하는지에 대한 내용입니다.

v0.3이 달랐음을 알게 된 순간

저는 같은 HR 질문을 다섯 번째 테스트하고 있었습니다:

"직원들은 유급 휴가를 몇 일 받나요?"

첫 실행: 전체 경로 — 검색(retrieval), LLM, 검증(verify), 인용(citations). 로컬 Ollama에서 약 4초 소요.

두 번째 실행: 즉시. 헤더: X-Cache: HIT.

같은 답변. 같은 인용. 토큰 소모 없음.

그때서야 이것이

Grounded LLM은 **문서 기반 어시스턴트 (document-grounded assistants)**를 위한 오픈 플랫폼이자 Grounded Spec v1입니다:

• 오직 사용자의 지식 베이스 (knowledge base) 내에서만 답변합니다.
• 모든 응답에서 **출처를 인용 (cites sources)**합니다.
• 검색 (retrieval) 결과가 답변을 뒷받침할 수 없을 때 **거절 (refuses)**합니다.
• 검색된 컨텍스트를 바탕으로 **숫자를 검증 (verifies numbers)**합니다 (±0.01).
• **사용자가 제어하는 인프라 (infrastructure)**에서 실행됩니다.
• "노트북에서 보기에 괜찮았다" 수준이 아닌, **측정 가능한 검색 품질 (measurable retrieval quality)**을 제공합니다.

포지셔닝 라인:

인용, 숫자 검증, 측정 가능한 검색 품질을 갖춘 문서 기반 어시스턴트를 위한 오픈 표준 — 귀하의 인프라에 배포 가능합니다.

비목표 (Non-goals): 임의의 에이전트 그래프 (agent graphs), 지식 베이스(KB) 없는 일반 채팅, 클라우드 종속 (cloud lock-in), Glean과의 기능적 동등성.

우리는 위젯의 개수가 아니라, **신뢰 (trust) + 재현 가능한 품질 (reproducible quality) + 준수성 (conformance)**으로 경쟁합니다.

랜딩 페이지: kantik001.github.io/grounded-llm

v0.1 → v0.3 한눈에 보기

스펙의 본질은 변하지 않았습니다. 레퍼런스 구현체 (reference implementation)가 날카로운 이빨을 갖게 되었습니다.

다이어그램 살펴보기 (재미있는 부분)

1. 클라이언트 (Clients) — 네 개의 문, 하나의 신뢰 경계 (trust boundary)

• Web chat — 레퍼런스 UI
• Python SDK / REST — 통합 개발자 (integrators)
• Telegram Mini App — 선택적인 필드 채널
• Agents (gRPC) — v0.3의 새로운 문

동일한 플랫폼입니다. 진입점만 다를 뿐입니다. 인증 (auth), 세션 (sessions), 정책 (policy)은 여전히 Go가 담당합니다.

2. Go 서버 :8080 — 검색이 아닌 오케스트레이션 (orchestration)

Go는 기업이 실제로 감사 (audit)하는 작업을 수행합니다:

Python은 검색 (retrieval)을 수행합니다. Go는 신뢰 (trust)를 담당합니다. 의도적으로 설계되었습니다.

3. Python RAG — 하이브리드 검색 (hybrid retrieval) + 에이전트 계약 (agent contract)

HTTP  :5000  →  /rag/context     (채팅 경로)
gRPC  :50051 →  Retriever/Retrieve (에이전트 경로)

내부 동작:

• 하이브리드 BM25 + dense + RRF
• 벡터 백엔드: Chroma / Qdrant / pgvector
• 선택적 리랭커 (키워드 또는 크로스 인코더)

에이전트는 청킹 전략을 재구현할 필요가 없습니다. 그들은 채팅 UI가 사용하는 것과 동일한 검색 기능을 호출합니다 — 안정적인 protobuf 계약(grounded.rag.v1)을 통해 제공됩니다.

4. Redis :6379 — 조용한 영웅

두 개의 캐시, 두 개의 수명 주기, 두 개의 소유자:

이것이 HR/법률 비서에게 중요한 이유:

• 반복되는 정책 질문은 첫 번째 히트 이후 무료입니다.
• 재인덱싱 시 캐시된 답변이 조용히 변경되지 않습니다 (키에 도메인/테넌트/모델 포함).
• HTTP 트레이스에서 캐시 동작을 증명할 수 있습니다 — 구매팀은 영수증을 좋아합니다.

5. LLM — 하나의 인터페이스, 세 가지 현실

{% raw %}

LLM_PROVIDER=openai   # OpenRouter / 모든 OpenAI 호환 클라우드
LLM_PROVIDER=ollama   # docker compose --profile ollama
LLM_PROVIDER=vllm     # docker compose --profile vllm  (NVIDIA)

코드 포크가 없습니다.

준수성 (Conformance): 홍보하지 말고 증명하세요

첫날부터 우리의 베팅은 다음과 같았습니다: 누구나 실행할 수 있는 규칙 + 테스트를 공개한다.

pip install -r conformance/requirements.txt
python -m conformance spec          # 오프라인 OpenAPI 계약 (contract)
python -m conformance check --url http://localhost:8080

여러분의 배포 환경이 Grounded-compatible하다면, 제 저장소(repo)를 포크(fork)하지 않고도 이 테스트를 통과할 수 있습니다.

v0.3은 명세(spec)를 대체한 것이 아닙니다. 레퍼런스 구현체(reference implementation)가 단순한 데모로 치부되기 어렵게 만들었습니다.

퀵 스타트 (15일이 아닌 15분)

git clone https://github.com/kantik001/grounded-llm.git
cd grounded-llm
cp .env.example .env
...

docker pull ghcr.io/kantik001/grounded-llm-server:0.3.0
docker pull ghcr.io/kantik001/grounded-llm-python:0.3.0
docker pull ghcr.io/kantik001/grounded-llm-webapp:0.3.0

템플릿 팩 (HR, IT 지원, 법률 FAQ):

python scripts/init_pack.py install hr
python scripts/reindex_rag.py

업계 내 위치 (v0.3에서도 여전히 유효함)

향후 계획

• 외부 준수성 채택자 (External conformance adopters) — 여러분의 배포 환경에서 CLI를 실행하고, Spec v2를 위한 이슈(issue)를 제기해 주세요.
• grounded-agent — gRPC Retriever + MCP Gateway 상에서의 ReAct 루프 구현
• 부하 테스트 (Load tests) — 동시성 환경에서의 캐시(cache) + 하이브리드 경로 증명

만약 여러분이 기업용 RAG (Enterprise RAG), 온프레미스 LLM (On-prem LLM), 또는 OSS 준수성 (OSS conformance) 관련 업무를 하고 계신다면, RFC-0001에 대한 피드백을 진심으로 부탁드립니다.

행동 촉구 (Call to action)

1. v0.3.0 사용해 보기: 릴리스 노트 (Release notes) · docker compose up 실행 또는 GHCR :0.3.0 이미지 풀(pull)
2. Star / watch 하기: 기업용 그라운딩 (Enterprise grounding)에 관심이 있다면: github.com/kantik001/grounded-llm
3. 준수성 테스트 (Run conformance) 실행: 여러분의 스택에서 테스트를 실행하고, Spec v2에 무엇이 포함되어야 하는지 알려주세요.
4. 평가 사례 (Eval case) 기여: 검색(retrieval) 버그를 수정할 때 평가 사례를 기여해 주세요 — GOOD_FIRST_ISSUES.md 참조
5. Part 1 읽기: 시작된 배경 이야기를 놓치셨다면 읽어보세요: Building an open standard for grounded document assistants

요약 (Summary)

저는 아버지의 원예 논문들로 시작했습니다.

v0.1은 선언문 (Manifesto)이었습니다.

v0.3은 제가 실제 파일럿 프로젝트에 배포할 플랫폼입니다.

MIT · Grounded Spec v1 · Landing · Architecture source PNG