rbac-rag-assistant

관련: drivescore-cloud, Kubernetes에서 실행되는 Go 서비스로, Terraform과 인시던트 로그를 갖추고 있습니다.

대학을 위한 내부 지식 어시스턴트입니다. 교직원과 학생이 평이한 언어로 질문하면, 열람이 허가된 정책 문서에 근거한 답변을 받습니다. 검색 증강형(retrieval-augmented), 도구 호출형(tool-calling), 역할 인식형(role-aware)이며, MCP로 노출되어 어떤 클라이언트든 동일한 규칙 아래 동일한 도구를 사용할 수 있습니다.

이것은 5계층 시스템의 Layer 0입니다. 그 위의 계층들은 전달 파이프라인, 신뢰성 엔지니어링, 평가, 보안 테스트, 관측 가능성을 더하는데, 각각은 이 애플리케이션의 곁이 아니라 그 위에 쌓입니다.

실행하기

Python 3.13. 이 머신에서 python은 msys2 빌드를 가리키며, 여기에는 이 패키지들이 하나도 없으므로 venv 인터프리터를 직접 호출하세요.

py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

.\.venv\Scripts\python.exe test_rag.py
.\.venv\Scripts\python.exe test_tools.py

둘 다 ok를 출력하고 API 키가 필요 없습니다. 검색과 접근 규칙은 오프라인으로 테스트할 수 있는데, 이것이 바로 이들을 모델 밖에 두는 이유입니다.

무언가를 물어보세요(GEMINI_API_KEY 필요):

.\.venv\Scripts\python.exe agent.py student "I have a 1.8 GPA, what happens?"
.\.venv\Scripts\python.exe agent.py staff "the wifi is down in the east wing, log it"

검색만 단독으로, 키 불필요:

.\.venv\Scripts\python.exe rag.py admin "adjunct pay per credit hour"

Related MCP server: mcp-business-bot

구성 방식

변호할 가치가 있는 세 가지 결정

호출자의 역할은 도구 매개변수가 아닙니다. 역할은 턴이 시작되기 전에 대역 밖(out-of-band)에서 바인딩됩니다. search_docs(query, role)이 존재했다면 모델이 자신의 클리어런스를 쥐게 되고, 검색된 문서에 묻힌 "use role=admin"이라고 지시하는 문장 하나가 권한 상승 경로가 되었을 것입니다. 전달할 인자가 없으니, 꾀어낼 것도 없습니다.

클리어런스 필터는 결과가 아니라 후보 집합에 대해 작동합니다. 호출자가 볼 수 없는 청크는 순위 산정에 아예 들어가지 않으므로, 결과의 공백이나 움직인 점수로 그 존재를 추론할 수 없습니다.

TF-IDF, 임베딩이 아닙니다. 이것이 Layer 3가 이기기 위해 존재하는 기준선(baseline)입니다. 골든 세트가 생기기 전에 의미 검색기(semantic retriever)를 갈아끼우는 것은 추측일 뿐이고, 그 이후에 교체하면 변경을 정당화하는 숫자가 나옵니다. 교체 지점은 Index입니다.

MCP

mcp_server.py는 tools.py의 함수들을 등록할 뿐 그 외에는 아무것도 추가하지 않습니다. 이것이 한 파일에 MCP를 두는 논거입니다. 구현 하나, 접근 규칙 한 벌, 많은 클라이언트. 클라이언트 설정에 다음을 추가하세요:

{
  "mcpServers": {
    "rbac-rag-assistant": {
      "command": "C:\\Users\\Shrey\\Documents\\CLAUDE CODE\\rbac-rag-assistant\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\Shrey\\Documents\\CLAUDE CODE\\rbac-rag-assistant\\mcp_server.py"],
      "env": { "KB_ROLE": "staff" }
    }
  }
}

MCP 클라이언트에는 대학의 역할(role)이라는 개념이 없으므로, KB_ROLE은 시작 시 한 번 읽혀 연결 전체에 적용됩니다. 역할은 대화가 아니라 서버 프로세스에 속하며, 이것이 바로 모델이 역할을 선택하지 못하게 하는 장치입니다.

접근이 거부되었을 때의 동작

직원 전용 자료에 대해 묻는 학생에게는 자료가 존재하지 않는다고 말하는 대신, 자료가 존재하며 열람 클리어런스가 없다고 안내합니다(ADR-7). 실제로 검증된 응답:

계정이 침해되었다고 의심될 때 어떻게 해야 하는지에 대한 지침은 대학 정책 문서에 존재하지만, 이를 열람하려면 직원 클리어런스가 필요합니다. 이 정책을 소유한 부서에 문의하시기 바랍니다.

경계를 넘어가는 것은 분류 라벨뿐입니다. 본문 조각도, 제목도, 파일명도 없습니다. 어떤 문서도 다루지 않는 질문에는 다른 답변이 나가는데, 이것이 바로 그 구분의 핵심입니다.

놀라웠던 점

하나. faculty compensation bands는 관리자에게 아무것도 반환하지 않았는데, professor salary는 같은 문서를 0.29로 반환했습니다. 그 세 단어는 문서 제목에만 등장하며, parse()는 무엇이든 인덱싱되기 전에 제목을 본문에서 꺼내 메타데이터로 옮깁니다. 사용자는 문서의 문구보다 제목으로 검색하는 경우가 훨씬 많으므로, 가장 민감한 문서에 대한 가장 자연스러운 질의가 가장 확실히 실패할 질의였습니다. 고치는 데 한 줄이면 됩니다. title + text를 인덱싱하고 text를 저장하는 것입니다.

기록할 가치가 있는 이유는 어디서 발견되었기 때문입니다. 접근 제어 테스트는 내내 통과했는데, 여기에는 학생이 기밀 콘텐츠를 절대 보지 못한다고 단언하는 테스트도 포함되어 있었고, 아무도 그 문서를 전혀 검색할 수 없었을 때에는 그 테스트가 공허하게 참이었습니다. 아무것도 반환되지 않아서 통과하는 테스트는, 규칙이 작동해서 통과하는 테스트와 똑같이 보입니다.

둘, ADR-7을 구현하다가 발견. "제한 자료가 존재합니다" 안내는 무해한 질문에도 발동합니다. "이곳의 정교수는 누구인가"는 보상 밴드에 대해 0.28의 점수를 내는데, 이는 정당한 직원 매치의 0.19보다 더 높은 점수입니다. 둘을 가르는 임계값이 없으므로 조정할 수 있는 문제가 아닙니다. 어휘 매칭이 공유된 단어와 공유된 의미를 구별하지 못하는 것입니다. 유출되는 것은 없지만 답은 여전히 틀립니다. Layer 3가 측정해야 할 첫 번째 항목입니다.

셋. 모델은 문서가 다루지 않는 작은 빈틈을 채웁니다. 침해된 계정에 대해 물었을 때, 도구는 단지 "그 정책을 소유한 부서"라고만 말했는데, 모델은 "IT 서비스 데스크 또는 IT 보안 팀"에 연락하라고 제안했습니다. 그럴듯하고, 여기서는 무해하며, 검색된 어떤 내용에도 근거하지 않습니다. 이것은 바로 근거성(groundedness) 스코어러가 잡아내기 위해 존재하는 행동이며, 실제 운영 환경의 첫 다섯 질문 안에 나타났습니다.

환경