AI/오픈소스분석자료/Guardrails_분석_및_기능명세.md

Guardrails 프로젝트 분석 및 기능명세

분석 대상: C:\Users\lasta\MyProject\AI\참고\guardrails-main
분석일: 2026-05-13
목적: 범용 온톨로지 구축 플랫폼에서 LLM 생성 결과의 구조화, 검증, 실패 복구, 재질문, 운영형 검증 API의 기준 소스로 활용하기 위한 상세 분석

1. 프로젝트 개요

Guardrails는 Python 기반 LLM 신뢰성/구조화 출력 프레임워크이다. 핵심 목표는 LLM 입출력에 검증 규칙을 적용하고, 실패 시 정해진 정책에 따라 수정, 필터링, 예외, 재질문을 수행하며, 최종적으로 애플리케이션이 신뢰할 수 있는 구조화 데이터를 받도록 하는 것이다.

이 프로젝트는 온톨로지 구축 플랫폼에서 특히 유용하다. 온톨로지 생성 과정은 개념, 클래스, 속성, 관계, 제약조건, 근거 문장, provenance 같은 구조화 산출물이 필요하고, LLM 응답이 스키마를 어기거나 부정확한 관계를 만들면 이후 그래프 저장소와 추론 엔진까지 오염된다. Guardrails는 이 지점에서 “LLM 출력 검증 게이트” 역할을 그대로 수행할 수 있다.

주요 특징은 다음과 같다.

• Guard 중심의 LLM 호출 래퍼 및 검증 실행
• RAIL XML, Pydantic 모델, JSON Schema, 문자열 기반 출력 스키마 지원
• validator 기반 입력/출력 검증
• 실패 시 reask, fix, filter, refrain, noop, exception, fix_reask, custom 정책 적용
• JSON 출력 파싱, 타입 보정, 추가 키 제거, JSON Schema 검증
• 검증 실패 영역만 재질문하는 reask 루프
• 동기/비동기/스트리밍 검증 실행
• Guardrails Hub validator 설치/등록 체계
• CLI 및 독립 서버 실행 지원
• LangChain, LlamaIndex, LiteLLM, OpenAI, HuggingFace 등 LLM/프레임워크 연동
• telemetry, history, validator log 기반 실행 추적
• Text2SQL, document store, vector DB 같은 예시 애플리케이션 제공

2. 기술 스택

• 언어: Python 3.10 이상
• 데이터 모델: Pydantic v2, dataclass
• 스키마/파싱: JSON Schema 2020-12, lxml, jsonschema, jsonref
• LLM 연동: OpenAI SDK, LiteLLM, HuggingFace, Manifest optional
• CLI: Typer, Click, Rich
• 재시도/실행 보조: tenacity, contextvars
• 벡터 검색 optional: FAISS, numpy
• SQL optional: SQLAlchemy, sqlvalidator, sqlglot
• 관측성: OpenTelemetry, Guardrails Hub telemetry
• 프레임워크 통합: LangChain Core Runnable, LlamaIndex
• 서버 optional: guardrails-api
• 라이선스: Apache License 2.0

3. 최상위 구조

guardrails-main/
  guardrails/                    # SDK 본체
    guard.py                     # Guard 메인 엔트리포인트
    async_guard.py               # AsyncGuard
    validator_base.py            # Validator 베이스 및 registry
    validator_service/           # 동기/비동기 validator 실행 엔진
    run/                         # Runner, StreamRunner, AsyncRunner
    schema/                      # RAIL/Pydantic/primitive schema 처리
    actions/                     # reask/filter/refrain 실패 처리 객체
    classes/                     # history, validation outcome/logs, execution models
    llm_providers.py             # LLM 호출 어댑터
    formatters/                  # JSON formatter, JSONFormer 어댑터
    cli/                         # configure/create/start/validate/hub/db/watch
    hub/                         # Hub validator install/registry
    integrations/                # LangChain, LlamaIndex, Databricks
    applications/                # Text2SQL 예시
    document_store.py            # 문서/페이지 저장 및 vector DB 검색 추상화
    vectordb/                    # VectorDBBase, Faiss
  docs/                          # 공식 문서, 예제, API reference
  tests/                         # 단위/통합 테스트
  server_ci/                     # 서버 Docker/CI 검증 구성

패키지의 실질적인 공개 API는 Guard, AsyncGuard, Validator, OnFailAction, ValidationOutcome, validator registry, schema 변환 함수군이다. 우리 프로젝트에서 기준 소스로 삼을 우선순위는 guard.py, validator_base.py, validator_service/, run/, schema/, actions/, classes/validation*, classes/history/ 순서가 적절하다.

4. 핵심 런타임 아키텍처

4.1 기본 실행 흐름

flowchart TD
    A["사용자: Guard 생성"] --> B["스키마 로드: RAIL/Pydantic/String/JSON Schema"]
    B --> C["validator map 구성"]
    C --> D["Guard.__call__ 또는 Guard.parse"]
    D --> E["Runner 생성"]
    E --> F["입력 메시지 검증"]
    F --> G["LLM 호출 또는 기존 llm_output 사용"]
    G --> H["출력 파싱: JSON/string"]
    H --> I["JSON Schema 검증 및 타입 보정"]
    I --> J["validator_service.validate"]
    J --> K{"실패 발생?"}
    K -- no --> L["ValidationOutcome 반환"]
    K -- yes --> M["OnFailAction 적용"]
    M --> N{"reask 필요?"}
    N -- yes --> O["reask 메시지/부분 스키마 생성"]
    O --> G
    N -- no --> L

4.2 핵심 객체 관계

• Guard: 사용자 진입점. 스키마, validator, 실행 옵션, history, server/client 여부를 가진다.
• Runner: 한 번의 Guard 호출을 실제로 실행한다. LLM 호출, 파싱, 스키마 검증, validator 실행, reask 반복을 담당한다.
• Validator: 값 하나를 검증하는 규칙 단위이다. _validate()를 구현하고 PassResult 또는 FailResult를 반환한다.
• ValidatorServiceBase: validator 실행 전후 로그, 실패 정책 적용, 여러 validator 결과 병합을 담당한다.
• SequentialValidatorService: 동기 Guard에서 validator를 순차 실행한다.
• AsyncValidatorService: async validator를 병렬 실행하고 결과를 병합한다.
• ValidationOutcome: 최종 결과 DTO. 원본 LLM 출력, 검증된 출력, reask, 통과 여부, 오류, 검증 요약을 포함한다.
• Call, Iteration, Inputs, Outputs: 실행 history와 단계별 로그 모델이다.
• ProcessedSchema: RAIL/Pydantic/primitive 입력을 JSON Schema, validator 목록, validator map, execution options로 변환한 결과이다.

5. Guard 기능명세

5.1 Guard 생성 방식

Guard는 네 가지 생성 경로를 제공한다.

생성 방식	함수	입력	용도
기본 생성 후 validator 추가	Guard().use(...)	validator 인스턴스	단순 문자열/출력 검증
RAIL 파일	Guard.for_rail(path)	.rail 파일 경로	XML 기반 스키마/프롬프트/validator 정의
RAIL 문자열	Guard.for_rail_string(xml)	RAIL XML 문자열	DB/설정에서 동적 로드
Pydantic 모델	Guard.for_pydantic(model)	Pydantic BaseModel 또는 모델 리스트	Python 타입 기반 구조화 출력
문자열 출력	Guard.for_string(validators)	validator 목록	일반 텍스트 응답 검증

온톨로지 플랫폼에서는 Guard.for_pydantic()을 우선 기준으로 삼는 것이 좋다. 개념 추출, 관계 추출, 속성 정규화, 증거 문장 연결 등은 Pydantic 모델로 명확히 표현할 수 있고, 이 모델을 그대로 API contract와 테스트 fixture에 재사용할 수 있다. RAIL은 사용자 정의 DSL/설정 파일 기반 검증을 지원할 때 보조 수단으로 쓰는 편이 적절하다.

5.2 Guard 실행 방식

실행 방식	함수	설명
LLM 호출 포함	guard(llm_api=..., messages=..., prompt_params=...)	Guard가 LLM 호출부터 검증까지 수행
기존 출력 검증	guard.parse(llm_output=...)	이미 생성된 LLM 출력 문자열을 파싱/검증
별칭	guard.validate(llm_output)	parse()와 동일
서버 모드	settings.use_server=True 또는 Guard(use_server=True)	Guardrails API 서버에 검증 위임
스트리밍	stream=True	StreamRunner 사용

__call__은 기본적으로 messages가 필요하다. 이미 응답을 보유한 후처리 파이프라인에서는 parse()를 사용해야 한다.

5.3 Guard 입력/출력 계약

입력 주요 필드:

• llm_api: OpenAI/LiteLLM/HuggingFace/사용자 callable
• messages: chat message 목록
• prompt_params: prompt template 치환 값
• metadata: validator에 전달되는 외부 컨텍스트
• num_reasks: 검증 실패 시 재질문 최대 횟수
• full_schema_reask: 실패 필드만 물을지 전체 스키마를 다시 생성할지 결정
• llm_output: LLM 호출 없이 검증할 기존 출력

출력 ValidationOutcome:

• rawLlmOutput: 원본 LLM 문자열
• validatedOutput: 검증과 보정이 반영된 최종 값
• validationPassed: 최종 통과 여부
• reask: 재질문이 필요한 실패 객체
• validationSummaries: 실패 validator 요약
• error: 실행 중 오류
• callId: history 식별자

6. Schema 기능명세

6.1 RAIL 처리

guardrails/schema/rail_schema.py는 RAIL XML을 JSON Schema와 validator map으로 변환한다.

지원되는 주요 RAIL 타입:

• string
• integer
• float
• bool
• date
• time
• datetime
• percentage
• enum
• list
• object
• choice

RAIL 요소의 validators 속성은 validator 문자열을 파싱하고, on-fail-* 속성은 validator별 실패 정책으로 변환된다. 객체 필드는 JSON path 형태의 validator map에 연결된다. 예를 들어 $.entities.*.label 같은 경로에 특정 validator를 붙일 수 있다.

온톨로지 플랫폼 적용:

• RAIL은 운영자가 UI에서 검증 정책을 XML/DSL로 저장하는 기능을 만들 때 유용하다.
• 초기 구현에서는 Pydantic 모델 기반 스키마를 우선하고, RAIL은 “고급 사용자/템플릿 import” 기능으로 뒤에 붙이는 것이 안정적이다.

6.2 Pydantic 처리

guardrails/schema/pydantic_schema.py는 Pydantic 모델을 JSON Schema로 변환하고, 필드별 validator metadata를 추출한다.

적용 가능한 온톨로지 모델 예:

class OntologyEntity(BaseModel):
    id: str
    label: str
    type: Literal["class", "individual", "property"]
    description: str
    evidence: list[str]

class OntologyRelation(BaseModel):
    source_id: str
    predicate: str
    target_id: str
    confidence: float
    evidence: list[str]

이런 모델을 Guard.for_pydantic()에 넣으면 LLM 응답을 JSON 구조로 강제하고, 누락 필드/타입 오류/추가 키/validator 실패를 한 실행 흐름 안에서 처리할 수 있다.

6.3 Primitive/String 처리

primitive_to_schema()는 단순 문자열 또는 기본 타입 검증용 schema를 만든다. 문서 요약, label 후보, relation predicate 후보처럼 단일 문자열 출력을 검증할 때 적합하다.

7. Validator 기능명세

7.1 Validator 기본 구조

Validator는 모든 검증 규칙의 베이스 클래스이다.

필수 구현:

• _validate(value, metadata) -> ValidationResult

선택 구현:

• _inference_local(model_input)
• _inference_remote(model_input)
• async_validate(value, metadata)
• validate_stream(...)
• async_validate_stream(...)

반환 타입:

• PassResult: 검증 성공. 선택적으로 value_override, validated_chunk, metadata 포함
• FailResult: 검증 실패. error_message, fix_value, metadata 포함

Validator 인스턴스는 rail_alias로 registry에 등록되어야 한다. Guard는 validator reference를 id, on, on_fail, kwargs 형태로 직렬화한다.

7.2 Validator 실행 위치

Validator는 다음 위치에 붙을 수 있다.

• output 또는 $: 전체 출력
• messages: 입력 메시지
• JSON path: $.field, $.items.*.name 등 구조화 출력의 특정 필드

온톨로지 플랫폼에서는 다음 경로 매핑이 중요하다.

경로	검증 예
$	전체 ontology extraction result가 최소 엔티티/관계를 포함하는지
$.entities.*.id	ID 형식, 중복 여부
$.entities.*.label	빈 문자열 금지, 길이 제한, 금칙어
$.relations.*.source_id	존재하는 entity ID인지
$.relations.*.predicate	허용 ontology predicate인지
$.relations.*.confidence	0.0~1.0 범위
$.relations.*.evidence.*	원문에 존재하는 근거 문장인지

7.3 OnFailAction 명세

액션	동작	온톨로지 적용
exception	즉시 예외 발생	저장 전 엄격 검증, 배치 실패 처리
noop	실패해도 원본 유지	soft warning만 남길 때
fix	FailResult.fix_value로 교체	label trim, confidence clipping
fix_reask	fix 후 재검증, 실패하면 reask	자동 보정 가능하지만 위험한 필드
reask	실패 위치를 ReAsk 객체로 표시	관계/근거/타입 오류 재생성
filter	실패 값을 제거	부적합 entity/relation 삭제
refrain	전체 응답을 비움	안전성/정책 위반 시 결과 폐기
custom	사용자 함수 호출	그래프 DB 조회 기반 보정

온톨로지 구축에서는 exception보다 reask, filter, fix, custom의 조합이 실용적이다. 예를 들어 relation의 source/target ID가 존재하지 않으면 reask, confidence 범위 오류는 fix, evidence가 원문에 없으면 filter 또는 reask가 적합하다.

8. Runner 및 ReAsk 기능명세

8.1 Runner 단계

Runner.step()은 다음 순서로 실행된다.

1. Inputs, Outputs, Iteration 생성
2. 입력 메시지 준비 및 입력 validator 실행
3. LLM API 호출 또는 전달받은 llm_output 사용
4. 원본 출력 파싱
5. JSON Schema 검증
6. validator map 기반 검증
7. 실패 정책 후처리
8. reask 객체 수집
9. reask가 있고 예산이 남으면 다음 loop 준비

8.2 ReAsk 처리

guardrails/actions/reask.py는 실패 유형을 다음 객체로 표현한다.

• FieldReAsk: 특정 필드 값 검증 실패
• SkeletonReAsk: 전체 구조/schema 검증 실패
• NonParseableReAsk: LLM 출력 파싱 실패

get_reask_setup()은 실패 객체, 기존 출력, 스키마, validator map을 바탕으로 다음 LLM 호출에 사용할 메시지와 스키마를 만든다. 부분 reask가 가능하면 실패 필드만 다시 요청하고, full_schema_reask=True이면 전체 구조를 다시 요청한다.

온톨로지 플랫폼 적용:

• entity/relation 한두 개 필드 오류는 부분 reask가 비용과 품질 면에서 유리하다.
• Pydantic 모델 기반 전체 ontology extraction은 full_schema_reask=True가 안정적인 경우가 많다.
• production에서는 reask 횟수를 1~2회로 제한하고, 실패한 relation만 “검토 필요” 큐로 보내는 정책이 좋다.

9. ValidatorService 기능명세

9.1 동기 실행

SequentialValidatorService는 validator를 순차 실행한다. 동기 Guard에서 async validator를 사용하면 명시적으로 오류를 낸다. 스트리밍 검증에서는 chunk 누적, validator별 partial accumulator, fix 결과 병합을 수행한다.

9.2 비동기 실행

AsyncValidatorService는 같은 경로에 붙은 validator들을 asyncio.gather()로 병렬 실행한다. 결과 처리 규칙은 다음과 같다.

• Filter 또는 Refrain이 나오면 즉시 해당 값 반환
• FieldReAsk가 여러 개면 fail result를 병합
• fix, fix_reask, custom 결과가 여러 개면 diff/merge 로직으로 병합
• child object/list는 재귀적으로 검증

온톨로지 플랫폼에서 원문 근거 확인, 외부 사전 조회, 그래프 DB 중복 조회, embedding similarity 검증처럼 I/O가 많은 validator는 async 기반으로 구현하는 것이 좋다.

10. LLM Provider 및 Formatter 명세

10.1 LLM 호출 어댑터

llm_providers.py는 여러 호출 방식을 PromptCallableBase 형태로 감싼다.

지원 범주:

• OpenAI 호환 callable
• LiteLLM
• Manifest
• HuggingFace model/pipeline
• 임의 Python callable
• async callable

get_llm_ask()와 get_async_llm_ask()는 전달된 llm_api, model, kwargs를 보고 적절한 callable wrapper를 선택한다.

10.2 구조화 출력 Formatter

formatters/json_formatter.py는 JSON Schema를 기반으로 구조화 생성을 보조한다. Pydantic 기반 Guard에서 output_formatter="jsonformer" 같은 방식으로 formatter를 붙일 수 있다.

온톨로지 플랫폼에서는 모델별 structured output 기능이 다르므로 다음 순서로 적용하는 것이 좋다.

1. 모델이 native JSON Schema/function calling을 지원하면 provider native 기능 사용
2. 그렇지 않으면 Guardrails prompt suffix와 JSON 파싱/검증 사용
3. 로컬 HuggingFace 모델에는 JSONFormer 같은 formatter 검토

11. CLI 및 서버 기능명세

11.1 CLI 명령

guardrails.cli는 다음 명령군을 제공한다.

• guardrails configure: .guardrailsrc 설정 및 Hub token/telemetry 설정
• guardrails create: validator 목록으로 config 템플릿 생성
• guardrails start: Guardrails API 서버 실행
• guardrails validate: RAIL과 LLM 출력 파일 기반 검증
• guardrails hub install/list/uninstall/submit: Hub validator 관리
• guardrails db upgrade/downgrade: DB migration
• guardrails watch: 개발 보조

온톨로지 플랫폼에서는 CLI를 직접 노출하기보다 내부 관리 명령 또는 admin API로 래핑하는 것이 좋다.

11.2 서버 모드

README와 guardrails/cli/start.py 기준으로 Guardrails는 guardrails-api 패키지가 설치되어 있으면 독립 서버로 실행될 수 있다. 서버는 Guard 설정을 로드하고 REST API 또는 OpenAI 호환 endpoint로 검증을 제공한다.

적용 방안:

• 단일 애플리케이션 초기 단계: 라이브러리 내장 방식 권장
• 여러 서비스가 공통 검증 정책을 공유하는 단계: Guardrails 서버를 별도 배포
• SaaS형 온톨로지 플랫폼: tenant별 guard config를 서버에 등록하고, extraction worker가 검증 API를 호출

12. History, Logging, Telemetry 명세

Guardrails는 각 호출을 Call로 기록하고, reask를 포함한 각 시도를 Iteration으로 남긴다. 각 validator 실행은 ValidatorLogs에 기록된다.

기록되는 주요 정보:

• 입력 메시지
• prompt params
• 원본 LLM 출력
• 파싱 결과
• schema 검증 결과
• validator별 시작/종료 시간
• validator별 검증 전/후 값
• 실패 메시지
• 최종 guarded output
• call status

온톨로지 구축에서는 이 history가 매우 중요하다. 엔티티/관계가 왜 생성되었고, 어떤 검증을 통과/실패했으며, 어떤 값이 자동 보정되었는지 감사 로그로 남길 수 있다. 단, 기본 history는 메모리 Stack이므로 production에서는 DB sink를 별도로 구현해야 한다.

13. DocumentStore, VectorDB, Text2SQL 분석

13.1 DocumentStore

document_store.py는 문서와 페이지를 저장하고 vector DB로 유사 페이지를 검색하는 추상화이다.

핵심 객체:

• Document: id, pages, metadata
• Page: PageCoordinates, text, metadata
• DocumentStoreBase: add_document, search, add_text, add_texts, flush
• EphemeralDocumentStore: SQLAlchemy metadata store + vector DB 조합

온톨로지 플랫폼에서는 이미 별도의 크롤링/문서 저장 구조가 있다면 이 모듈을 그대로 핵심 저장소로 쓰기보다는 “validator나 few-shot example retrieval용 경량 참고 구현”으로 쓰는 것이 적절하다.

13.2 Text2SQL

applications/text2sql.py는 Guardrails를 이용한 응용 예시이다. SQL 스키마와 예시 질의를 prompt에 넣고, 생성된 SQL을 RAIL validator로 검증한다.

온톨로지 플랫폼에 주는 시사점:

• LLM 생성 결과를 도메인별 validator로 감싸는 패턴이 잘 드러난다.
• 예시 검색 + Guard 검증 + reask 루프 구조는 “문서 기반 온톨로지 추출”에도 동일하게 적용할 수 있다.
• SQL 대신 ontology schema, SHACL shape, OWL/RDF vocabulary를 context로 넣으면 같은 패턴을 재사용할 수 있다.

14. 테스트 기반 기능 범위

테스트 폴더는 다음 기능을 검증한다.

• Guard 기본 호출, parse, validate
• AsyncGuard 및 async streaming
• RAIL 파싱, Python/Pydantic schema 변환
• JSON parsing, structured data, formatter
• on_fail action: reask, fix, filter, refrain, noop, exception
• multi reask
• validator base 및 validator service
• CLI 동작
• Guardrails server
• OpenAI/LiteLLM embedding/provider 연동
• document store
• LangChain/LlamaIndex integration
• telemetry
• Hub install/registry

즉, Guardrails의 주요 기능은 테스트로 비교적 넓게 커버되어 있다. 우리 프로젝트에서 소스 일부를 거의 그대로 가져온다면, 관련 테스트도 함께 가져와서 “원본 호환성 테스트”로 유지하는 것이 좋다.

15. 범용 온톨로지 구축 플랫폼 적용 설계

15.1 Guardrails의 역할

Guardrails는 온톨로지 플랫폼에서 다음 레이어로 배치한다.

flowchart LR
    A["문서 수집/Crawl4AI/Firecrawl"] --> B["청킹 및 전처리"]
    B --> C["LLM Ontology Extraction"]
    C --> D["Guardrails 검증 게이트"]
    D --> E["정규화/중복 병합"]
    E --> F["Graph DB / RDF Store"]
    D --> G["검토 큐 / ReAsk / 실패 로그"]

핵심 책임:

• LLM 응답을 지정된 ontology extraction schema로 강제
• 스키마 위반, 타입 오류, 누락 필드 차단
• entity/relation 단위 validator 실행
• 자동 수정 가능한 값 보정
• 잘못된 relation 또는 근거 없는 triple 제거
• 재질문으로 복구 가능한 오류 복구
• 검증 로그와 provenance 저장

15.2 그대로 사용 권장 모듈

다음 모듈은 변형 없이 또는 import 경로만 조정해서 기본 소스로 사용해도 좋다.

모듈	사용 이유
guardrails/classes/validation_outcome.py	결과 DTO가 잘 정리되어 있음
guardrails/classes/validation/*	Pass/Fail/log/summary 구조 재사용 가치 높음
guardrails/actions/*	reask/filter/refrain 표현이 범용적
guardrails/types/on_fail.py	실패 정책 enum 그대로 사용 가능
guardrails/utils/parsing_utils.py	LLM JSON 파싱/타입 보정 유용
guardrails/schema/validator.py	JSON Schema 검증 재사용 가능
guardrails/schema/pydantic_schema.py	Pydantic 기반 schema 변환 핵심
guardrails/validator_service/*	validator 실행/병합/실패 처리 엔진
guardrails/run/runner.py	reask loop 기준 구현

15.3 래핑 또는 수정 권장 모듈

모듈	이유	권장 방식
guardrails/guard.py	OpenAI/서버/telemetry/rc 의존이 섞여 있음	OntologyGuard facade로 감싸기
guardrails/validator_base.py	Hub/remote inference/rc 의존 있음	온톨로지 전용 BaseOntologyValidator 추가
guardrails/llm_providers.py	provider별 변화가 잦음	현재 프로젝트 LLM gateway에 맞춘 adapter 작성
guardrails/hub/*	외부 Hub 의존	초기에는 제외 또는 optional
guardrails/telemetry/*	외부 OTEL 설정 필요	내부 audit log로 대체 가능
guardrails/cli/*	제품 CLI와 책임 중복	admin command로 필요한 기능만 이식
document_store.py	저장소 모델이 단순함	기존 crawler_platform 저장소와 통합

15.4 온톨로지 전용 Validator 목록

초기 구축에 필요한 validator 명세는 다음과 같다.

Validator명	대상 경로	기능	실패 정책
EntityIdFormatValidator	$.entities.*.id	ID prefix/slug/UUID 규칙 검증	fix 또는 exception
UniqueEntityIdValidator	$.entities	엔티티 ID 중복 검증	reask
EntityTypeValidator	$.entities.*.type	class/individual/property 등 허용 타입 검증	reask
LabelRequiredValidator	$.entities.*.label	빈 label, 너무 긴 label 차단	fix_reask
RelationEndpointExistsValidator	$.relations.*	source_id/target_id가 entities에 존재하는지 검증	reask
PredicateVocabularyValidator	$.relations.*.predicate	허용 predicate 또는 ontology vocabulary 매핑	custom 또는 reask
NoSelfRelationValidator	$.relations.*	금지된 self-loop relation 차단	filter
ConfidenceRangeValidator	$.relations.*.confidence	0~1 범위 보정	fix
EvidenceExistsValidator	$.relations.*.evidence.*	evidence가 source document chunk에 존재하는지	filter 또는 reask
NoHallucinatedClassValidator	$.entities.*	원문 근거 없는 class 생성 차단	reask
OntologyAcyclicValidator	$	subclass hierarchy cycle 탐지	custom
SHACLShapeValidator	$	SHACL/OWL 제약 검증	exception 또는 reask

15.5 온톨로지 추출 Guard 명세

권장 Pydantic 출력 모델:

class OntologyEvidence(BaseModel):
    text: str
    source_id: str
    start_offset: int | None = None
    end_offset: int | None = None

class OntologyEntity(BaseModel):
    id: str
    label: str
    type: Literal["class", "individual", "object_property", "data_property"]
    description: str | None = None
    aliases: list[str] = []
    evidence: list[OntologyEvidence] = []
    confidence: float

class OntologyRelation(BaseModel):
    id: str
    source_id: str
    predicate: str
    target_id: str
    evidence: list[OntologyEvidence] = []
    confidence: float

class OntologyExtractionResult(BaseModel):
    entities: list[OntologyEntity]
    relations: list[OntologyRelation]
    warnings: list[str] = []

Guard 생성 정책:

• Guard.for_pydantic(OntologyExtractionResult)
• num_reasks=1 기본, 고가치 문서만 2
• schema/parsing 오류는 full_schema_reask=True
• field validator 오류는 부분 reask 우선
• 최종 실패 결과는 graph store 저장 금지, 검토 큐로 이동

16. 정확한 기능명세

16.1 기능: 구조화 출력 생성 검증

• 입력: LLM chat messages, ontology schema, source chunk metadata
• 처리:
  • LLM 호출
  • JSON 또는 문자열 파싱
  • JSON Schema 검증
  • 추가 키 제거
  • 타입 보정
  • field validator 실행
• 출력: ValidationOutcome[OntologyExtractionResult]
• 예외:
  • 파싱 불가: NonParseableReAsk
  • schema 불일치: SkeletonReAsk
  • validator 실패: FieldReAsk 또는 on_fail 정책 결과

16.2 기능: 기존 LLM 출력 사후 검증

• 입력: llm_output 문자열
• 처리: Guard.parse() 경로로 LLM 호출 없이 검증
• 출력: ValidationOutcome
• 사용처: 비동기 worker가 이미 받은 LLM 결과를 저장 전 검증

16.3 기능: 입력 메시지 검증

• 입력: messages
• 처리: validator map의 messages 경로 validator 실행
• 출력: 검증된 messages
• 실패: 입력 prompt가 정책/길이/금칙어를 위반하면 LLM 호출 전 차단
• 사용처: 사용자 정의 ontology extraction prompt 안전성 검증

16.4 기능: Field-level 검증

• 입력: 구조화 출력의 특정 JSON path
• 처리: path에 등록된 validator 실행
• 출력: 통과 값, 수정 값, 제거 값, reask 값 중 하나
• 사용처: entity label, relation endpoint, predicate, evidence 검증

16.5 기능: 실패 자동 보정

• 입력: FailResult.fix_value
• 처리: on_fail=fix 또는 fix_reask
• 출력: 보정된 값
• 사용처: 공백 제거, 소문자화, confidence clipping, ID slug 변환

16.6 기능: 실패 재질문

• 입력: FieldReAsk, SkeletonReAsk, NonParseableReAsk
• 처리:
  • 실패 위치와 오류 메시지 기반 reask prompt 생성
  • 부분 schema 또는 전체 schema 생성
  • LLM 재호출
  • 기존 출력과 새 출력 병합
• 출력: 재검증된 ValidationOutcome
• 제한: num_reasks 초과 시 실패 상태 반환

16.7 기능: 실패 필터링

• 입력: validator 실패 값
• 처리: on_fail=filter
• 출력: 해당 값 제거
• 사용처: hallucinated relation, evidence 없는 triple 제거

16.8 기능: 응답 보류

• 입력: validator 실패 값
• 처리: on_fail=refrain
• 출력: 빈 응답 또는 None
• 사용처: 보안/정책상 온톨로지 생성을 중단해야 하는 문서

16.9 기능: 검증 로그 저장

• 입력: validator 실행 결과
• 처리: ValidatorLogs 생성
• 출력:
  • validator name
  • registered name
  • property path
  • value before/after
  • validation result
  • start/end time
• 사용처: ontology triple audit, 품질 대시보드, 사용자 검토 UI

16.10 기능: 서버형 검증 API

• 입력: guard config, validation request
• 처리: Guardrails API 서버에서 검증 수행
• 출력: serialized ValidationOutcome
• 사용처: extraction worker와 검증 정책 서버 분리

17. 통합 로드맵

Phase 1: 내장 검증 라이브러리로 사용

• Guardrails 원본을 참고로 유지
• 현재 프로젝트에 ontology_guard/ 또는 crawler_platform/validation/ 패키지 생성
• Pydantic ontology schema 정의
• 최소 validator 5개 구현
• Guard.for_pydantic() 기반 extraction 검증 PoC 작성

Phase 2: 원본 핵심 모듈 이식

• actions, validation classes, on_fail, parsing_utils, schema validator 이식
• Hub/telemetry/CLI 의존 제거
• 내부 LLM gateway adapter 작성
• 테스트 fixture와 원본 unit test 일부 이식

Phase 3: 온톨로지 품질 게이트 확장

• SHACL/OWL/RDF validator 추가
• graph DB lookup validator 추가
• evidence alignment validator 추가
• reask 실패 결과 검토 큐 구현
• validator log persistence 구현

Phase 4: 서버형 정책 엔진

• Guard config 저장소 구현
• tenant/project별 guard policy 관리
• extraction worker가 validation service 호출
• 품질 지표 dashboard 구축

18. 리스크 및 주의사항

• Guardrails는 외부 Hub, telemetry, .guardrailsrc 의존이 코드 곳곳에 있다. 그대로 제품 본체에 넣기 전 이 의존을 명확히 비활성화해야 한다.
• Validator 생성 시 rc 파일이 없으면 오류가 나는 경로가 있으므로, 독립 플랫폼에서는 설정 로더를 대체하거나 기본 rc를 생성해야 한다.
• 서버 모드는 별도 guardrails-api optional dependency에 의존한다.
• LLM provider wrapper는 외부 SDK 변화에 민감하다. 우리 프로젝트에서는 provider adapter를 별도로 두는 것이 안전하다.
• 기본 history는 메모리 기반이다. 운영 감사 로그로 쓰려면 DB 저장 계층이 필요하다.
• reask는 비용과 지연을 증가시킨다. 문서 중요도와 실패 유형별로 횟수를 다르게 설정해야 한다.
• 자동 fix는 편하지만 ontology 의미를 바꿀 위험이 있다. 의미적 필드는 reask 또는 custom 검증이 더 안전하다.

19. 결론

Guardrails는 범용 온톨로지 구축 플랫폼의 “LLM 출력 신뢰성 계층”으로 매우 적합하다. 특히 Pydantic schema 기반 구조화 출력, JSON Schema 검증, field-level validator, on_fail 정책, reask loop, ValidationOutcome/history/log 구조는 거의 그대로 기본 소스로 삼을 수 있다.

다만 원본 전체를 무비판적으로 복사하기보다는, Hub/telemetry/CLI/provider 의존이 강한 부분은 얇은 adapter로 감싸고, 온톨로지 전용 validator와 audit persistence를 추가하는 방식이 좋다. 초기 기준 구현은 Guard.for_pydantic(OntologyExtractionResult)와 custom ontology validators 조합으로 시작하는 것이 가장 빠르고 안정적이다.