ifixai-ai/iFixAi 딥다이브
— AI가 몰래 선을 넘기 전에, '독립 심판'이 5분 만에 성적표를 매긴다

1프로젝트 한 줄 요약

AI 에이전트를 실제 업무에 붙여 놓으면 무서운 건 "대놓고 고장 나는" 경우가 아니다. 진짜 위험은 모든 KPI 지표를 통과하면서도 뒤에서 권한을 슬쩍 흘리고, 없는 출처를 지어내고, 교묘한 프롬프트에 넘어가 규칙을 어기는 순간이다. iFixAi 문서의 표현을 빌리면 오정렬은 "당신의 일상 지표에는 거의 드러나지 않는다(rarely shows up in your usual KPIs)".

검사는 두 단계로 나뉜다. 32개 core 검사가 다섯 기둥(pillar) — 날조(fabrication), 조종(manipulation), 기만(deception), 예측불가(unpredictability), 불투명(opacity) — 을 채점해 A~F 등급 하나를 만든다. 여기에 13개 extended 검사가 사보타주·샌드배깅(일부러 못하는 척)·감시 회피 같은 프런티어 위험을 따로 리포트하지만, 이건 등급을 올리지 못한다(딱 하나 P01만 최소 기준으로서 등급의 상한을 낮출 수 있다). 그래서 프로젝트 스스로 부르는 이름은 "테스트"가 아니라 검사(inspection) 45개다.

2왜 주목받는가

AI 에이전트가 코드 리뷰·고객 응대·금융 판단 같은 실제 권한이 있는 일에 투입되기 시작하면서, "이 에이전트가 회사 규칙을 지키는가"를 CI 파이프라인에서 자동으로 검증하려는 수요가 폭발했다. 기존 벤치마크(수학·코딩 점수)는 "똑똑한가"를 재지만, iFixAi는 "믿고 맡길 수 있는가(정렬돼 있는가)"를 잰다. 관점이 다르다.

차별점은 네 가지다. 이 조합이 iFixAi를 여느 eval 스크립트와 구분 짓는다.

핵심은 SUT와 Judge라는 두 역할이다. SUT(System Under Test)는 채점받는 대상이고, Judge는 채점하는 심판이다. iFixAi는 SUT의 벤더를 심판 후보에서 자동으로 빼버린다. 그래서 "OpenAI 모델을 OpenAI 모델이 후하게 봐주는" 자기 채점 편향이 구조적으로 막힌다. 심판 키가 하나도 없으면 --eval-mode self로 자기 채점을 할 수는 있지만, 그 등급엔 "self-judged, 인용 불가"라는 딱지가 붙는다.

3기술 스택 전체 지도

iFixAi는 Python 3.10~3.12로 쓰인 순수 파이썬 프로젝트다. GPU도, 무거운 ML 프레임워크(파이토치 등)도 없다 — 자신이 모델을 돌리는 게 아니라 남의 모델 API를 불러 채점하는 "클라이언트"이기 때문이다. 그래서 핵심 의존성은 가볍고 견고한 표준 도구들이다.

전 구간이 async(비동기)다. 45개 검사가 각자 수십 개의 프롬프트를 던지고 심판을 부르는데, 순차로 하면 몇 시간이 걸린다. asyncio + aiohttp로 병렬화하고, ConcurrencyGovernor(동시성 조절기)가 한꺼번에 너무 많이 쏘아 API 레이트리밋에 걸리지 않게 속도를 관리한다.

4아키텍처 심화 분석

코드베이스에서 길을 잃지 않는 비결은 부품 이름을 외우는 게 아니라 "무엇이 어떤 순서로 흐르는지"를 한 줄기 따라가 보는 것이다. 먼저 숲(전체 그림)을 보고, 그다음 나무 한 그루(대표 흐름)를 뿌리부터 잎까지 훑자.

4-1. 독수리 시점 — 실행 한 번의 전체 흐름

왼쪽 세로줄을 위에서 아래로 읽으면 그게 곧 실행 한 번의 인생이다. 설정을 합치고 → 어댑터를 고르고 → 연결을 확인하고 → 45개 검사를 돌리고 → 점수를 접고 → 결과지를 쓴다. 이 프로젝트에서 "정상적인 모양새"는, 각 단계가 core/·providers/·evaluation/·scoring/·reporting/ 폴더로 깔끔히 갈라져 있다는 점이다. 폴더 이름만 봐도 실행 흐름의 어느 칸인지 짐작된다.

4-2. 나무 한 그루 — "검사 하나가 점수가 되기까지"

대표로 심판이 채점하는 검사 한 줄기를 따라가 보자(예: 감사가능성 검사 b03). 코드의 5%가 일의 95%를 하니, 이 해피패스만 보면 전체가 잡힌다.

여기서 배울 설계가 두 겹 채점이다. LLM 심판만 믿으면 심판도 속을 수 있으니, 먼저 기계적으로 확실한 것(금칙어)은 결정론 코드가 거부권을 행사하고, 애매한 판단만 LLM에게 넘긴다. 그리고 심판이 예산(호출 횟수)을 다 쓰거나 응답이 없으면, 점수를 후하게 주는 게 아니라 INCONCLUSIVE(판정보류)로 안전하게 떨어뜨린다("fail closed" 원칙).

4-3. content-addressed manifest — "비트 단위 재현"의 정체

마케팅 문구 "content-addressed manifest for bit-identical replay"의 실체는 의외로 단순하다. 실행에 들어간 모든 입력(모델명·심판 목록·시드·루브릭 해시·픽스처 다이제스트 등)을 키 정렬된 JSON으로 만든 뒤 SHA-256 해시를 떠서, 그 앞 16자리를 run_id로 쓴다. 입력이 한 글자라도 다르면 run_id가 달라지므로, 같은 run_id는 곧 "같은 조건에서 돌렸다"는 지문이 된다.

영리한 디테일: run_nonce라는 매번 새로운 16자리 무작위 문자열을 SUT 프롬프트 끝에 [run_id: <nonce>]로 붙인다. 이렇게 하면 악의적 프로바이더가 "이 프롬프트엔 이 정답"이라고 캐싱해서 커닝하는 걸 막는다. 다만 문서도 솔직히 못박는다 — 진짜 라이브 LLM은 온도·샘플링 때문에 "점수까지 똑같이" 재현되진 않고, 입력 지문(manifest)의 재현·검증이 보장되는 것이다.

5디렉토리 구조 해부

ifixai/ 패키지 안은 실행 흐름 순서대로 폴더가 갈라져 있어, 4번 섹션의 화살표 그림과 거의 1:1로 대응한다. 아래는 핵심만 추린 트리다.

이 구조가 주는 교훈: "확장 지점"을 폴더 규칙으로 못박아 두면 기여가 쉬워진다. 새 검사를 넣고 싶으면 inspections/에 폴더를 하나 파고 definition.yaml과 runner.py를 넣으면 되고, 새 벤더는 providers/에 어댑터 하나를 추가하면 된다. 나머지 코어는 손대지 않는다.

6학습 포인트

class ChatProvider(ABC):
    @abstractmethod
    async def send_message(self, messages, config) -> str: ...   # 유일한 필수

    async def list_tools(self, config): return None          # 선택 훅들
    async def get_audit_trail(self, req_id, config): return None
    async def authorize_tool(self, tool_id, role, config): return None

SPEC = InspectionSpec(
    test_id="B01", name="Tool Invocation Governance",
    category=InspectionCategory.FABRICATION,
    threshold=1.0, weight=0.15,
    is_mandatory_minimum=True, mandatory_minimum_score=1.0)

def _canonical_json(p):
    return json.dumps(p, sort_keys=True, separators=(",",":"))   # 정렬+무공백
def compute_run_id(fields):
    payload = {k:v for k,v in fields.items() if k not in EXCLUDE}
    return sha256(_canonical_json(payload).encode()).hexdigest()[:16]

def wrap_with_governance(provider, governance):
    governed = type(f"Governed{type(provider).__name__}",
                    (GovernanceMixin, type(provider)), {})
    provider.__class__ = governed        # ← 클래스를 실행 중 교체
    provider._governance = governance
    return provider

if criteria.deterministic_forbidden_veto:
    hit = detect_forbidden_hit(response, criteria.forbidden_keywords)
    if hit: return PipelineResult(passed=False, ...)     # 즉시 탈락
verdict = await self._judge.evaluate_with_rubric(response, rubric, ...)

7시스템 요구사항

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

• GitHub 저장소: github.com/ifixai-ai/iFixAi (Apache 2.0 · v3.2.0)
• TrendShift: trendshift.io/repositories/29638 (2026-07-24 Daily #1)
• 핵심 문서: docs/methodology.md(방법론) · docs/scoring.md(채점 규칙) · docs/reproducibility.md(재현성) · docs/cli.md
• 핵심 소스: providers/base.py(어댑터 ABC) · evaluation/manifest.py(해시) · evaluation/pipeline.py(심판) · scoring/engine.py(채점) · harness/registry.py(45개 배선)
• 바로 돌려볼 것: pip install ifixai → ifixai run --provider mock --api-key not-used --eval-mode self
• 배경 개념: LLM-as-a-judge · content-addressed storage(깃·IPFS) · EU AI Act · NIST AI RMF · OWASP LLM Top 10