> ## Documentation Index
> Fetch the complete documentation index at: https://docs.starfort.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Guardian
> Guardian은 콘텐츠를 Guard Policy에 따라 검사하고 PASS, MASK, BLOCK 판단을 반환하는 엔진입니다.
**Guardian**은 AI 요청 경로상에 위치하는 분석 엔진입니다. 콘텐츠를 받아 자신에게 할당된 **Guard Policy**에 따라 평가하고, 판단의 근거가 되는 탐지 항목과 함께 [액션](/ko/v1.2/concepts/actions-pass-mask-block)(`PASS`, `MASK`, `BLOCK`)을 반환합니다.
## System Guardian과 Project Guardian
플랫폼에 등록된 마스터 정의입니다(예: `VLM-OCR` 프리셋). Guardian이 지원하는 기능 — Input Type, Policy Type, process type, 운영 한도, 모델 구성 — 을 선언합니다.
**Project** 내부에 생성하는 사본입니다. 어떤 Guard Policy가 할당되는지, 모델 구성 재정의, 활성 카테고리, 자체 수명 주기 등 운영 설정을 소유합니다. API 키와 Desktop Agent가 호출하는 대상이 바로 이것입니다.
Account Admin이 프로젝트에서 [Guardian을 등록](/ko/v1.2/admin/register-guardian)할 때 System Guardian 프리셋을 선택하면, 프로젝트는 구성할 수 있는 자체 Project Guardian을 갖게 됩니다. 하나의 Project는 **여러 개의 Project Guardian**을 운영할 수 있습니다 — 예를 들어 서비스마다 하나씩, 또는 정책 묶음마다 하나씩 — 그리고 각각은 독립적인 [Kill Switch](/ko/v1.2/concepts/organization-hierarchy) 토글 단위입니다.
### 사양은 고정되고, 설정은 사용자의 것입니다
"왜 내 변경이 적용되지 않았는가?"라는 혼란의 대부분은 두 가지 규칙으로 설명됩니다.
* **System Guardian의 사양은 등록 후 변경 불가능합니다.** 일단 등록되면 이름, 설명, Endpoint URL, 가시성(scope + Enabled)만 변경할 수 있습니다. 기능 사양 — 지원하는 Input Type, Policy Type, process type, 한도, 모델 구성 키 — 은 고정됩니다.
* **Project Guardian은 생성 시점에 그 사양을 복사하여 독립적으로 소유합니다.** 이후 System Guardian을 수정해도 소급 전파되지 **않습니다**. 다만 라이브 Endpoint URL만 계속 참조됩니다. 호환되는 Policy Type 집합(검사할 *수 있는* 대상)은 System Guardian에 의해 고정되지만, 그 범위 내의 운영 값(할당된 Guard Policy, 텍스트/파일 한도, 활성 카테고리, 모델 구성)은 사용자가 조정할 수 있습니다.
## Input Type
Guardian은 어떤 종류의 콘텐츠를 검사할 수 있는지 선언합니다. Guardian별로 일부를 활성화합니다.
| Input Type | 예시 |
| ---------- | ---------------------------------- |
| Text | 프롬프트, 메시지 |
| Image | PNG, JPG, WebP, GIF, … |
| Audio | WAV, MP3 |
| Video | MP4 |
| Document | PDF, DOCX, XLSX, PPTX, TXT, CSV, … |
| Archive | ZIP |
카테고리 지원은 3단계 수명 주기를 따릅니다. System Guardian이 처리할 수 있는 카테고리를 **선언**하고, Project Guardian이 그 일부를 **활성화**하며, 런타임에 Bastion이 들어오는 콘텐츠를 활성 집합에 대해 **검증**합니다. (Desktop Agent 프로젝트에서는 콘텐츠 유형이 파싱 규칙에 의해 결정되고, API 프로젝트에서는 선언된 content-part 유형에서 가져옵니다.) 활성화되지 않은 유형의 콘텐츠는 거부됩니다(또는 파일의 경우 검사 없이 통과됩니다 — 미지원 파일 처리 참고). 이들이 API 요청에 어떻게 매핑되는지는 [멀티모달 입력](/ko/v1.2/api/multimodal)을 참고하세요.
## Process type: input과 output
Guardian은 **process type**별로 콘텐츠를 평가합니다 — process type은 Guardian이 정의하는 자유 형식 레이블입니다(일반적으로 `input`과 `output`).
* **`input`** — 모델로 *전달되는* 콘텐츠(사용자의 프롬프트).
* **`output`** — 모델에서 *돌아오는* 콘텐츠(응답).
각 process type은 **자신이 호환되는 Policy Type**을 선언합니다. Guard Policy는 process type별로 할당되므로, 들어가는 길에 PII를 마스킹하고 예를 들어 나가는 길에 허용되지 않은 주제를 차단할 수 있습니다. 호환 집합이 비어 있는 process type은 **Policy-not-required**입니다 — 정책 슬롯이 표시되지 않고 호출 시 `policies`도 전송되지 않습니다(추가 입력만으로 실행됨).
## Guardian 계약(contract)
플랫폼이 Guardian을 구동할 수 있도록, 모든 Guardian 구현은 작은 기준 계약을 충족해야 합니다.
* **Stateless** — 모든 요청은 독립적으로 처리됩니다. 사용자 관리, 인증, 트레이스 로깅은 Guardian이 아니라 Bastion의 역할입니다.
* **정규화된 형식** — Guardian Input Format을 받아 Guardian Output Format으로 응답합니다.
* **세 가지 기준 엔드포인트** — `/guardian`(분석), `/info`(자기 기술), `/health`(생존 여부만), 그리고 선택적인 모델별 진단.
`/info`는 \*\*진실의 원천이 아니라 시드(seed)\*\*입니다. 등록 시점에 그 응답이 폼을 미리 채우고, System Admin이 저장한 결과가 시스템의 진실의 원천이 됩니다.
### Guardian Fail-Closed
Guardian은 **완전히 분석한 요청에 대해서만** 성공 응답을 반환합니다. 분석을 완료할 수 없는 경우 — 모델이 다운되거나, 파일을 추출할 수 없거나, 여러 모델 호출 중 하나라도 실패하는 경우(부분 실패) — 빈 탐지의 "성공"이 아니라 **HTTP 오류**를 반환합니다. 이는 "탐지 없음"이 항상 *분석했으나 아무것도 발견하지 못함*을 의미하도록 보장하므로, 장애가 조용히 PASS가 되는 일은 결코 없습니다.
## 모델 구성
각 Guardian은 유효 모델 구성을 가집니다 — 엔진 기본값에 프로젝트 수준의 재정의(예: `confidence_threshold`)가 병합된 것입니다. 관리자는 Guardian 상세 페이지에서 이를 확인하고 재정의할 수 있습니다.
Guardian은 정책이 할당되어 있고 **그리고** 해당 정책 버전이 적용되어 있을 때만 동작합니다. [정책 업데이트 버전 관리 및 적용](/ko/v1.2/admin/how-to/version-and-apply-policy)을 참고하세요.