시작하기: 로컬 근거 검색 도우미
첫 근거 검색 도우미 만들기: 완전한 로컬 기준선
작은 문서 모음으로 결정적이고 출처를 추적할 수 있는 응답 시스템을 만듭니다. 계약, 검색, 답변 보류를 구현해 언어 모델이나 에이전트를 추가하기 전의 기준선을 마련합니다.
출처 및 버전 정보
이 글의 목차
1. 문제와 약속
당직 엔지니어가 매뉴얼에서 “timeout retry”를 검색한다고 가정하세요. 대화형 에이전트 전에 공개 문서와 ID를 반환하고 어휘 근거가 없으면 보류하는 시스템을 만듭니다. 원문을 반환하며 LLM, 의미 검색, 안전한 운영 서비스가 아닌 향후 AI 앱의 검색 기준선입니다.
Python 파일과 별도 테스트를 만들고 응답 계약, 순위 계산, 알려진 실패, 추론 추가 위치를 설명합니다. 집중 학습 1–2회를 권하지만 실측 완료 시간은 아닙니다.
2. 선수 지식의 의미
함수는 입력을 출력으로 바꾸고 딕셔너리는 필드 이름을 정합니다. 집합은 중복을 제거해 반복 단어의 가중치가 늘지 않습니다. ID는 순서와 달리 안정적입니다. frozen dataclass는 실수로 재할당하는 일을 막지만 자료 인증이나 모음 교체를 막지는 않습니다.
기준선은 단순하고 고정된 비교 대상입니다. 보류는 규칙을 충족하지 못했다는 뜻이지 답이 없다는 증명이 아닙니다. 트레이스는 후보 순위를 기록합니다. 유창한 생성이나 높은 점수도 검색의 정확성을 보장하지 않습니다.
3. 아키텍처와 계약
D1은 재시도, D2는 키 교체, D3는 제한된 사고 기록입니다. CLI가 answer()를 호출하고 토큰화 전에 타입과 길이를 확인합니다. 점수와 트레이스 전에 공개 문서만 걸러 제한 ID 노출을 방지합니다. 로그인이나 테넌트가 없는 교육 정책이지 신원 기반 권한 시스템이 아닙니다.
출력은 status, text, source, trace이며 abstain이면 text와 source는 null입니다. 점수는 무차원이고 source는 ID입니다. 잘못된 입력은 ValueError입니다. 네트워크, 영속성, 부작용은 없습니다. HTTP를 추가하면 인증, 할당량, 기한, 민감 정보 제거가 별도로 필요합니다.
4. 점수 유도와 계산
Q는 정규화 질의 단어 집합이고 D는 문서 단어 집합입니다. Q의 포함 비율이라 비대칭이며 추가 문서 단어는 벌점을 받지 않습니다. “timeout retry”는 D1에서 2/2=1, D2에서 0/2=0입니다. D3는 0점이 아니라 제외됩니다. 임계값 0.5는 동률을 포함합니다.
“timeout missing”은 1/2로 반환되지만 전체가 뒷받침되지는 않습니다. “connection stalled”는 의미상 비슷해도 0입니다. 계산이 아닌 방법의 한계입니다. 임계값을 낮추면 약한 일치도 늘고 높여도 동의어는 해결되지 않습니다. 포함 비율은 신뢰도나 정답률이 아닙니다.
| ID | Q ∩ D | s(Q,D) |
|---|---|---|
| D1 | timeout, retry | 2/2 = 1 |
| D2 | ∅ | 0/2 = 0 |
5. 구현 선택과 한계
terms()는 소문자화 후 ASCII 영숫자를 추출합니다. 모델 토크나이저가 아니며 중일문 분할, 어간 추출, Unicode 정규화, 불용어 제거가 없습니다. 다섯 번역은 같은 영어 데이터를 사용합니다. 실제 다국어 시스템에는 언어별 분석과 평가가 필요합니다.
N개 문서의 평균 길이가 L이면 매 질의에 N×L 문자를 분석하고 O(N log N)으로 정렬합니다. 세 문서에는 적합합니다. 단어를 미리 계산한 뒤 역색인을 도입하고 원문과 함께 버전 관리하세요. 오래된 색인은 삭제된 근거를 가리킬 수 있습니다. ID 동점 처리로 결과를 안정화합니다.
6. 기준선을 이해한 뒤 확장하기
BM25는 빈도, 희귀성, 길이를 반영하고 밀집 검색은 표현 유사도를 추가하지만 충분한 근거를 보장하지 않습니다. 생성기에는 허용 자료만 전달하고 ID는 구조화해 보존하세요. 문서 명령은 비신뢰 데이터이며 인용을 검증해야 합니다. 완전한 RAG에는 수집, 최신성, 접근 검사, 충분성도 필요합니다.
모든 프레임워크를 더하지 마세요. RAG 종합 글로 한 가지 개선을 고르고 SDE로 모델 호출 경계를 이해하며 상태 있는 도구가 필요할 때 SRE로 진행하세요. 같은 홀드아웃 과제로 비교해야 데이터 변화를 개선으로 착각하지 않습니다.
7. 실습과 검증
빈 폴더에 assistant.py와 test_assistant.py를 저장하세요. Python 3.11 이상만 필요하고 추가 의존성, 다운로드, API 키는 없습니다. 난수를 쓰지 않아 시드도 필요 없습니다. 숨겨진 도우미 파일이나 원격 데이터 없이 전체 코드가 포함됩니다.
assistant.py
다운로드 assistant.py"""Offline, deterministic retrieval baseline. Python 3.11+, standard library only."""
import json
import re
import sys
from dataclasses import dataclass
@dataclass(frozen=True)
class Document:
id: str
text: str
audience: str = "public"
DOCS = (
Document("D1", "Retry timeout requests with backoff."),
Document("D2", "Rotate access keys every month."),
Document("D3", "Private incident recovery password.", "restricted"),
)
def terms(text):
return set(re.findall(r"[a-z0-9]+", text.lower()))
def answer(query, docs=DOCS, threshold=0.5):
if not isinstance(query, str) or len(query) > 2000:
raise ValueError("query must be a string of at most 2000 characters")
if not 0 < threshold <= 1:
raise ValueError("threshold must be in (0, 1]")
if len({d.id for d in docs}) != len(docs):
raise ValueError("duplicate document ID")
q = terms(query)
candidates = []
for doc in docs:
if doc.audience != "public":
continue # Filter before ranking or constructing the trace.
score = len(q & terms(doc.text)) / len(q) if q else 0.0
candidates.append((score, doc.id, doc.text))
candidates.sort(key=lambda row: (-row[0], row[1]))
trace = [{"id": d, "score": s} for s, d, _ in candidates]
if not candidates or candidates[0][0] < threshold:
return {"status": "abstain", "text": None, "source": None, "trace": trace}
_, doc_id, text = candidates[0]
return {"status": "evidence", "text": text, "source": doc_id, "trace": trace}
if __name__ == "__main__":
query = " ".join(sys.argv[1:]) or "timeout retry"
print(json.dumps(answer(query), indent=2))
test_assistant.py
다운로드 test_assistant.pyimport unittest
from assistant import answer, Document
class ContractTests(unittest.TestCase):
def test_known(self):
r = answer("timeout retry")
self.assertEqual((r["status"], r["source"]), ("evidence", "D1"))
self.assertEqual(r["trace"][0]["score"], 1.0)
def test_unknown_and_empty(self):
for query in ("", "quasar orbit", "日本語"):
self.assertEqual(answer(query)["status"], "abstain")
def test_no_private_trace(self):
r = answer("private incident recovery password")
self.assertEqual(r["status"], "abstain")
self.assertNotIn("D3", str(r))
def test_stable_tie(self):
docs = (Document("B", "retry"), Document("A", "retry"))
self.assertEqual(answer("retry", docs)["source"], "A")
def test_boundaries(self):
self.assertEqual(answer("timeout missing")["status"], "evidence")
self.assertEqual(answer("timeout missing extra")["status"], "abstain")
self.assertEqual(answer("retry", ())["status"], "abstain")
def test_invalid(self):
for query in (None, "x" * 2001):
with self.assertRaises(ValueError): answer(query)
with self.assertRaises(ValueError): answer("retry", threshold=0)
with self.assertRaises(ValueError): answer("retry", (Document("A", "x"), Document("A", "y")))
def test_lexical_failure_is_visible(self):
# Semantically similar wording is intentionally NOT solved by this baseline.
self.assertEqual(answer("connection stalled")["status"], "abstain")
if __name__ == "__main__":
unittest.main()
python3 assistant.py "timeout retry"
python3 assistant.py "quasar orbit"
python3 -m unittest -v test_assistant.py기본 입력은 evidence, D1,
자료, 질의, 권한을 고정하고 임계값만 0.75로 바꾸세요. 원복 후 문서 단어를 미리 계산하세요. 전자는 행동을 바꾸고 후자는 유지해야 합니다. 근거, 불충분 반환, 보류를 나누고 개발셋에서 조정한 뒤 미사용셋에서 보고하세요. 단위 테스트는 배포 품질 증거가 아닙니다.
독창적 면접 연습: 기업 기출문제가 아님
왜 1점이 정답의 증명이 아닌가요?
힌트: 단어 포함과 의미를 비교하세요. “do not retry timeout requests”는 모든 단어를 포함하지만 행동을 부정합니다. 부정과 함의를 다루지 않으므로 반례와 근거 검사가 필요합니다.
왜 트레이스 전에 필터링하나요?
힌트: 진단도 출력입니다. 원문을 숨겨도 ID와 점수가 노출될 수 있습니다. 먼저 제외하면 모든 출력에서 사라지지만 인증된 권한이 구현되는 것은 아닙니다.
답을 바꾸지 않고 어떻게 가속하나요?
힌트: 반복 작업을 찾으세요. 불변 자료 버전의 단어 집합을 캐시하고 점수와 동점 처리가 같은지 검증하세요. 문서나 분석기 변경 시 무효화하고 동등성을 확인한 뒤 측정하세요.
채점: 1은 정의, 2는 계산, 3은 전체 테스트 실행과 설명, 4는 새 실패와 공정 비교, 5는 독립 확장, 계약 유지, 남은 한계 설명입니다. 직업 인증은 아닙니다.