trigsight

제 작업에 대해 증명할 수 없는 주장을 하지 않는 AI 어시스턴트입니다.

생성되는 모든 사실적 진술은 빌드 시점에 해당 진술을 뒷받침하는 정확한 문장에 바인딩됩니다. 인용을 클릭하면 소스 페이지가 해당 문장으로 스크롤되고 강조 표시됩니다. 인용된 구절이 소스 문서에 존재하지 않으면 빌드가 실패합니다 — 검증할 수 없는 주장은 배포할 수 없습니다.

왜 만들었나

포트폴리오 챗봇은 작성자의 역량에 대해 주장합니다. 독자는 이를 확인할 방법이 없고, 확인하지 않을 타당한 이유도 있습니다: 측정된 일반 AI 검색의 인용 오류율은 60%를 넘고, 생성된 문장 중 단 51.5%만이 인용된 출처에 의해 완전히 뒷받침됩니다. 그래서 그 주장들은 할인되어 취급되고, 그 기능은 장식이 됩니다.

일반적인 해결책은 모델을 코퍼스에 근거시키고 기대하는 것입니다. 이는 환각에는 도움이 되지만 검증에는 도움이 되지 않습니다 — 독자는 여전히 전체 페이지 링크를 받고 특정 주장을 뒷받침하는 문장을 찾아야 합니다.

이것은 신뢰 모델을 뒤집습니다. 모델은 절대 링크를 쓰지 않습니다. 구절을 지목하면, 빌드가 문서가 실제로 말하는 내용의 인덱스와 대조하여 해석하거나 배포를 거부합니다.

Related MCP server: CiteGuard

측정 결과

3D 장면이 실행되는 상태에서 JavaScript가 2.8배 적습니다. 두 수치 모두 배포된 사이트에서 실제 전송된 brotli 용량이며, 동일한 하네스(bench/baseline/measure-payload.sh)로 각각 3회 측정했습니다 — 양쪽을 다르게 측정하여 이를 3.4배로 과장한 이유는 docs/05-results.md를 참조하세요.

검색, k=5에서 손으로 작성한 골든 쿼리 30개:

실제 임베딩은 Upstash Vector를 통한 1536차원, 코사인의 text-embedding-3-small입니다. 동일한 실행을 3번 했습니다. 무엇이 바뀌었는지 주목하세요: 재현율은 개선되지 않았고, 순위가 개선되었습니다. 이 코퍼스 크기에서 실제 임베딩은 더 관련성 높은 청크를 찾지 못하며, 찾은 청크의 순위를 더 높입니다 — 상위 6개만 모델에 도달하므로 이것이 중요한 지표입니다.

보장이 작동하는 방식

flowchart TB
  subgraph build["BUILD"]
    MDX["content/*.mdx"] --> N["normalise: collapse whitespace, casefold"]
    N --> IDX["passage index"]
    IDX --> VER{"every cited passage present exactly once?"}
    VER -->|no| FAIL["EXIT 1 — build fails"]
    VER -->|yes| OK["allowlist.json"]
  end
  subgraph run["REQUEST"]
    Q["question"] --> R["hybrid retrieve: BM25 + vector, RRF"]
    R --> M["model"]
    M -->|emits a cite token| RES{"in allowlist?"}
    OK --> RES
    RES -->|yes| CHIP["chip with text-fragment deep link"]
    RES -->|no| DROP["dropped"]
  end

모델에는 URL을 생성하는 메커니즘이 없으므로 잘못된 URL을 생성할 수 없습니다. 프롬프트 지침은 요청일 뿐입니다; 없는 능력은 불변 조건입니다.

보기보다 어려웠던 부분

#:~:text=을 일치시키는 브라우저는 렌더링된 텍스트와 비교하며, 지시문의 각 부분은 단일 요소 안에 있어야 합니다. 실제 디버깅 비용이 들었던 두 가지 결과가 있습니다:

• 원시 소스와 비교하면 브라우저가 잘 일치시키는 7개 구절 중 3개가 실패합니다 — 줄바꿈을 넘나들거나, 축소된 공백을 포함하거나, 대소문자가 다른 구절입니다. 거짓 실패를 만들어내는 검증기는 사용자가 이를 비활성화하도록 만듭니다.

• 인라인 마크업에 걸쳐 있는 구절은 별도의 DOM 노드로 렌더링되어, 평면화된 텍스트에 포함되어 있어도 전혀 일치시킬 수 없습니다. 34개 인용 중 2개가 이 상태였습니다: 바인딩된 것으로 보고되지만 실제로는 일치 불가능합니다. 빌드된 모든 페이지를 가져와 텍스트를 검색해야만 발견할 수 있었습니다.

둘 다 이제 회귀 테스트와 함께 적용됩니다. 검증기는 또한 각 구절이 정확히 한 번 나타나도록 요구하며, 그렇지 않은 경우 접두사로 모호성을 해결합니다 — 그렇지 않으면 브라우저가 조용히 잘못된 위치로 스크롤하여 성공처럼 보이는 정확성 버그가 발생합니다.

빠른 시작

npm ci
npm run dev          # http://localhost:3000

자격 증명이 필요 없습니다. AI_GATEWAY_API_KEY가 없으면 채팅 엔드포인트는 답변 대신 검색된 컨텍스트를 반환하므로 검색 자체를 독립적으로 확인할 수 있습니다.

직접 주장을 검증하기

npm run verify:citations                 # the gate: exits 1 on any unbound claim
npx tsx bench/citations/verify.ts --demo # watch it reject a fabricated passage
npm run eval:retrieval                   # recall@5 and MRR over the golden set
./bench/payload/measure.sh 3990 150      # initial JS against the budget
npm test                                 # 91 tests

위의 모든 숫자는 그중 하나에서 나옵니다. bench/는 커밋되며 결코 gitignore되지 않습니다 — 커밋되지 않은 하네스는 실제 결과를 검증할 수 없는 주장으로 만듭니다.

MCP 서버

POST /api/mcp — 상태 비저장 Streamable HTTP, 사양 2026-07-28. 설명 도구가 아닌 4개의 읽기 전용 검증 도구입니다:

find_evidence는 원래 *"이온 트랩에 대한 양자 암호화 연구"*를 확증했습니다. 벡터 레그는 최근접 이웃 검색입니다: 아무리 무관해도 항상 가장 가까운 청크를 반환합니다. 이를 소비하는 에이전트는 지어낸 자격을 반복할 것입니다. 이제 실제 어휘 중복을 요구하며, 손으로 작성한 주장 세트에 대해 참긍정 8/10, 거짓긍정 0/6으로 보정되었습니다.

한계

솔직하게 말하면, 마케팅처럼 읽히는 한계 섹션은 가치가 없기 때문입니다.

• 어휘 전용 대비 차이는 쿼리 하나만큼입니다. 34개 청크와 30개의 골든 쿼리에서 쿼리 하나는 재현율 0.033의 가치가 있습니다 — 따라서 어휘 전용과 하이브리드 사이의 0.034 재현율 차이는 단일 쿼리입니다. 이 표를 하이브리드가 일반적으로 우월하다는 증거로 읽지 마세요. 이는 하이브리드가 더 나쁘지 않고 이 코퍼스에서 순위를 더 잘 매긴다는 것을 보여줍니다.

• 제 예측 중 하나가 틀렸고, 그 이유는 교훈적입니다. 저는 실제 임베딩이 놓친 쿼리 하나를 해결할 것이라고 예측했습니다. 그렇지 않았습니다. 벡터 레그만 따로 조사해 보니 올바른 청크가 상위 5위 안에 들어오지 않았습니다 — 그 청크는 다섯 가지 주제를 다루는 1,340자이고, 답은 871자 지점에 있는 하나의 절이기 때문입니다. 그것의 단일 벡터는 다섯 가지 아이디어의 평균입니다. 이것은 임베딩 문제가 아니라 청킹 문제이며, 어떤 모델도 해결하지 못합니다. 지금 청커를 바꾸면 표가 만들려는 비교가 무효화되므로 패치 대신 기록했습니다. bench/retrieval/results/real-embeddings-2026-08-21.md를 참조하세요.

• 자격 증명이 없으면 벡터 레그는 의미론적 모델이 아닌 결정적 대체물로 저하됩니다. 검색은 여전히 BM25로 답하지만 품질은 확실히 낮아집니다 — 하네스는 모든 실행에서 백엔드를 명시하므로 없는 상태에서 숫자를 인용할 수 없습니다.

• 텍스트 조각은 설계상 취약합니다. 인용된 문장을 바꾸면 링크가 끊어집니다. 그것이 빌드 게이트의 요점입니다 — 끊어진 상태를 배포할 수 없습니다 — 하지만 산문을 편집할 때 인용도 갱신해야 하는 경우가 있다는 뜻입니다.

• 인용은 하나의 블록 요소 안에 있어야 합니다. 표 행과 단락에 걸친 텍스트가 가장 잘 뒷받침하는 주장은 단일 구절로 인용될 수 없습니다.

• 코퍼스가 작습니다(문서 6개, 청크 34개). 여기의 검색 수치는 대규모 코퍼스에 대한 예측으로 읽어서는 안 됩니다.

• 스트리밍 인용 해석이 없습니다. 칩은 메시지가 완료된 후에 렌더링되며, 스트리밍 중간에는 렌더링되지 않습니다.

기술 스택

Next.js 16.3.1 · React 19.2.8 (고정 — R3F 9 피어 >=19 <19.3) · TypeScript · Tailwind v4.3.3 · Velite + Zod · three 0.185.1 + R3F 9.7.0 (고정) · Vercel AI Gateway

라이선스

MIT — LICENSE를 참조하세요.