xerj 딥다이브
— AI가 내 자료를 찾아 읽게 하는 Rust 검색엔진

1프로젝트 한줄 요약

xerj는 내 컴퓨터나 서버에 있는 자료를 색인하고, 질문에 맞는 문서·코드 조각을 찾아주는 검색엔진입니다. 여기에 MCP 서버가 들어 있어 AI 에이전트도 검색 도구를 호출할 수 있습니다. AI에게 폴더 전체를 읽히는 대신, 질문에 필요한 근거를 먼저 검색해 전달하는 것이 핵심입니다.

예를 들어 “WAL 파일을 언제 지우는가?”라는 질문을 받으면, 모든 Rust 파일을 대화에 넣을 필요가 없습니다. 관련 함수와 설명을 검색하고 파일 경로·줄 번호를 확인하면 됩니다. 이때 답을 생성하는 주체는 연결한 AI이고, xerj는 근거를 찾는 계층을 담당합니다.

1-1. 사용 흐름을 네 단계로 나눠 보기

본문의 경로는 저장소 루트 기준이며, 주요 Rust 크레이트는 engine/crates/ 아래에 있습니다. 공통 의존성과 빌드 프로필은 engine/Cargo.toml에서, 파일 링크는 마지막 참고 목록에서 확인할 수 있습니다.

# 설치된 xerj가 있다는 전제의 로컬 학습 예시
# docs와 저장 데이터를 서로 다른 폴더에 둡니다.
xerj --insecure --data-dir ./xerj-lab/data

# 다른 터미널: 먼저 예상 작업량을 확인합니다.
xerj autoindex ./xerj-lab/docs --prefix study --dry-run
xerj autoindex ./xerj-lab/docs --prefix study
xerj autoindex map
xerj search --prefix study "write ahead log"

실행 파일 하나와 프로세스 하나는 다른 말입니다. xerj mcp는 표준 입출력으로 MCP를 제공하는 별도 실행 모드이며, 이미 실행 중인 검색 노드에 연결합니다. 검색 노드를 자동으로 시작하는 기능으로 이해하면 연결 단계에서 혼동하기 쉽습니다.

2왜 주목받는가

2-1. 에이전트에게 필요한 것은 파일 목록 다음의 단계

문자열 검색은 “어느 파일에 이 단어가 있나?”를 잘 해결합니다. 하지만 질문이 “이 코드베이스는 쓰기 실패를 어떻게 복구하나?”라면, 단어가 나타난 위치를 모은 뒤 중요한 구현을 골라내는 일이 남습니다. xerj는 순위와 문서 조각, 코드 선언 위치를 제공해 이 후속 작업을 줄이려 합니다.

소스에서 차별점이 드러나는 곳은 engine/crates/xerj-autoindex/src/extract/code.rs입니다. 파일 본문뿐 아니라 tree-sitter로 얻은 심볼과 선언별 레코드를 만듭니다. name, kind, line, code 같은 필드가 생기므로 검색 결과를 다시 소스 위치로 연결할 수 있습니다.

검색 결과를 에이전트가 곧바로 읽을 수 있는 단위로 만드는 것이, 이 프로젝트의 실용적인 차별점입니다. 다만 구문 트리에서 선언을 찾는 것과 컴파일러처럼 타입·호출 관계를 완전히 해석하는 것은 구별해야 합니다.

2-2. 여러 서비스를 조립하는 비용을 줄인다

작은 RAG 실험에서도 파일 파서, 전문 검색, 벡터 저장소, 임베딩 연결, 도구 서버를 조립하면 설정이 늘어납니다. xerj는 이를 한 제품의 기본 흐름으로 연결합니다. 다음 비교는 일반적인 사용 방식과 조합 비용에 대한 비교이며, 각 제품의 전체 기능을 나열한 표는 아닙니다.

2-3. 트렌딩 선정과 성능 증거를 구별하자

TrendShift Weekly #17 선정과 2026-10-23 GitHub 기준 스타 13,210개·포크 950개는 관심도의 신호입니다. 2026-06-30 생성된 저장소가 10월에 이 규모의 관심을 얻었다는 점은 눈에 띕니다. 그러나 관심이 늘어난 정확한 인과관계나 실제 서비스 채택률을 이 수치만으로 알 수는 없습니다.

README는 참조 코드를 검색하는 실험에서 토큰 사용을 줄였다고 소개합니다. 이는 프로젝트가 공개한 특정 과제·모델·자료에서의 결과입니다. 모든 에이전트 작업에 같은 절감률이 생긴다는 약속으로 읽으면 안 됩니다. 반복 질문의 정답 자료를 정해 두고 내 문서에서 검색 품질과 총 작업 시간을 함께 재는 편이 학습에 도움이 됩니다.

3기술 스택 전체 지도

중심은 Rust입니다. 의존성 선언은 허용 범위를, 잠금 파일은 실제로 선택된 버전을 보여줍니다. engine/Cargo.toml에는 내부 크레이트 18개와 ES YAML 테스트 실행기를 합쳐 작업 공간 구성원 19개가 있습니다. 패키지 공통 버전은 1.0.0-rc.98, 에디션은 2021입니다. 크레이트는 Rust의 라이브러리·실행 파일 묶음 단위입니다.

3-1. 백엔드: 연결을 기다리는 일과 계산하는 일

이 표의 선언은 engine/Cargo.toml, 해석된 버전은 engine/Cargo.lock 기준입니다. 예를 들어 rayon = "1.10"은 정확히 1.10.0만 쓰겠다는 뜻이 아닙니다. 허용 범위 안의 실제 선택을 잠금 파일에서 확인해야 합니다.

3-2. 검색과 자료 추출: 라이브러리 위에 직접 만든 엔진

BM25 점수와 HNSW 검색 구현은 각각 xerj-fts, xerj-vector에 있습니다. 다른 검색 서버를 내부에서 실행하는 구조로 이해하면 안 됩니다. 반대로 모든 바이트 처리까지 직접 만든 것도 아닙니다. 사전·압축·파서 같은 하위 라이브러리를 조합해 엔진을 구현합니다.

3-3. 프론트엔드: 빌드 없는 JavaScript와 Rust 자산 묶음

xerj-ux/는 HTML·CSS·브라우저 ES 모듈로 된 콘솔입니다. xerj-ux/src/app.js는 대시보드 등록부, 질의 계층, 화면 렌더러를 가져옵니다. 이 커밋의 추적 파일에는 package.json이 없으며, React·Vue 기반 앱으로 분류할 근거도 없습니다.

engine/crates/xerj-console-api/build.rs는 자산을 찾아 Rust 상수 테이블로 묶습니다. 확장자 허용 목록과 파일당 4 MiB 상한을 두며, engine/crates/xerj-console-api/src/spa.rs의 xerj_console_index()·serve()가 내장 자산을 제공합니다. 자산 폴더가 없을 때 빈 테이블을 만드는 예외 경로도 있습니다.

3-4. 인프라·빌드: 배포 속도보다 실행 성능을 우선한 프로필

# engine/Cargo.toml의 배포 설정 발췌
[profile.release]
opt-level = 3
lto = "fat"
codegen-units = 1
strip = true
panic = "abort"

링크 시점 최적화를 넓게 적용하는 대신 빌드가 무거워지는 선택입니다. 개발용 quick은 lto = false, codegen-units = 16, opt-level = 2입니다. 테스트용 ci-test는 테스트에 필요한 panic = "unwind"를 명시합니다. 프로필이 다르면 성능 숫자를 그대로 비교할 수 없습니다.

engine/crates/xerj-server/build.rs는 protox 0.7.2로 Protocol Buffers 정의를 읽고 Tonic 코드를 생성합니다. 호스트에 별도 protoc 실행 파일을 요구하지 않는 선택도 크로스 빌드의 복잡도를 줄입니다.

4아키텍처 심화 분석

4-1. 전체 시스템 구조

도식의 세 포트는 기본값입니다. 기본 바인딩 주소는 루프백이며, 포트 충돌 시 자동 변경은 기본 동작이 아닙니다. --auto-port를 켠 구성에서는 실제로 바인딩된 포트를 확인해야 합니다. 콘솔이 활성화되면 두 HTTP 포트의 /_xerj-console/ 경로에서 제공됩니다.

4-2. 설계 패턴 ① 어댑터: 입력과 프로토콜을 검색 핵심에서 분리

xerj-autoindex의 의존성에는 xerj-engine이 없습니다. 파일을 읽고 서버의 HTTP API로 보내는 클라이언트이기 때문입니다. PDF 파싱 실패를 검색 서버 내부의 함수 호출 실패와 같은 것으로 다루지 않아도 되는 구조입니다.

MCP 쪽도 같은 원리를 따릅니다. engine/crates/xerj-mcp/src/lib.rs의 run()이 입력 줄을 읽고, handle_message()가 initialize·tools/list·tools/call을 나눕니다. call_tool()은 도구 이름을 검증하고 검색 요청을 구성합니다.

// handle_message()의 분기 구조를 줄인 개념 예시
match method.as_str() {
    "tools/list" => tool_specs(),
    "tools/call" => call_tool(ctx, &msg).await,
    _ => method_not_found(),
}

위 코드는 구조 설명용이며 원문 전체가 아닙니다. 실제 구현은 요청의 id와 알림 여부, JSON-RPC 응답 외피까지 처리합니다. 도구 실행 오류는 isError: true인 도구 결과로 돌려주며, 알 수 없는 RPC 메서드와 구분합니다.

모든 MCP 도구가 단순 프록시는 아닙니다. build_semantic()은 검색 JSON을 조립하지만, 코드 검색·Hub 도구는 결과 정리나 별도 검색 흐름을 가집니다. “같은 API를 재사용한다”와 “도구가 아무 처리도 하지 않는다”를 구별해 읽어야 합니다.

4-3. 설계 패턴 ② 전략 교체: 임베딩을 하나의 인터페이스로 묶기

engine/crates/xerj-ai/src/embedder.rs의 Embedder는 Lexical, Proxy, 기능 조건부 Neural·Onnx를 열거형으로 표현합니다. 호출자는 embed_batch()를 통해 벡터를 받아 검색 흐름을 이어갑니다.

기본 local_embed()는 단어와 문자 3개 묶음을 해시 버킷에 넣습니다. 단어 가중치는 1.0, 문자 묶음은 0.35, 기본 차원은 384입니다. 마지막에는 L2 정규화로 벡터 길이를 맞춥니다. 학습된 언어 모델이 아니라 어휘 겹침을 숫자로 바꾼 것입니다.

// engine/crates/xerj-ai/src/local.rs의 실제 함수 형태
pub fn local_embed(text: &str, dims: usize) -> Vec<f32>

// 동작을 이해하기 위한 요약
단어 분리 -> 단어·문자 묶음 생성 -> 해시 버킷에 누적 -> L2 정규화
"running" -> "#ru", "run", "unn", "nni", "nin", "ing", "ng#"

신경망 모드는 --embed-mode neural로 선택하며 기본 모델 ID는 sentence-transformers/all-MiniLM-L6-v2입니다. engine/crates/xerj-ai/src/neural.rs의 MAX_TOKENS는 512이고, 같은 설정의 모델은 공유 레지스트리와 OnceCell을 통해 중복 로드를 줄입니다.

4-4. 설계 패턴 ③ 기록 후 공개: WAL과 일관된 읽기

engine/crates/xerj-storage/src/wal.rs의 WalWriter::append()는 변경을 로그에 남깁니다. 로그는 ZWAL 식별자, 세대, 순번, 작업 코드, 본문, 체크섬으로 구성됩니다. 재시작 시 WalReader::replay()가 로그를 읽고 아직 반영되지 않은 변경을 복구합니다.

Index::index_batch_turbo()에서는 collection_publication.begin()으로 공개 구간을 시작하고 store.wal_append_batch()를 호출한 뒤 메모리 검색 구조를 갱신합니다. 저장용 상태와 검색용 상태가 어긋난 순간을 읽기 요청이 완성된 결과로 받아들이지 않도록 순서를 관리합니다.

engine/crates/xerj-engine/src/collection_publication.rs의 try_admit_reader()·validate_reader()는 진행 중 쓰기 수와 세대 번호를 확인합니다. 가드가 완료·취소 표시 없이 해제되면 poisoned 상태를 남깁니다. 이는 일부 상태만 공개된 결과를 정상처럼 반환하지 않으려는 실패 처리입니다.

쓰기 성공, 디스크 내구성, 검색에서 보이는 시점은 서로 다른 계약이므로 각각 확인해야 합니다. 기본 WAL 정책은 batched이며 동기화 주기는 100ms입니다. 커널에 썼다는 사실과 전원 장애에도 살아남는 저장 장치 반영은 같은 말이 아닙니다.

또 Index::refresh()는 메모리 자료를 디스크 세그먼트로 쓰는 경로를 호출합니다. “refresh는 디스크에 쓰지 않는다”는 다른 엔진의 설명을 여기에 그대로 적용하면 틀립니다. WalWriter::prune_verified()도 로그 세대 전체를 지우기 전에 각 항목의 영속화 여부를 검증합니다.

4-5. 설계 패턴 ④ 결과 목록 합성: BM25와 벡터 순위의 융합

engine/crates/xerj-fts/src/bm25.rs의 Bm25Scorer::score_term()은 드문 단어의 중요도와 단어 빈도, 문서 길이를 결합합니다. 기본 상수는 k1 = 1.2, b = 0.75입니다. 반복 횟수가 늘어도 점수가 무한히 비례하지 않도록 포화시킵니다.

벡터 검색은 가까운 좌표를 찾습니다. Index::run_knn_hnsw()는 조건이 맞으면 HNSW 후보 탐색을 사용하고 저장 벡터로 다시 점수를 계산합니다. 하지만 후보의 점수가 정확하다고 후보 집합까지 전체 정답인 것은 아닙니다. HNSW는 근사 탐색입니다.

기본 RRF 하이브리드는 두 점수를 바로 더하지 않습니다. run_hybrid_with_deadline()이 하위 검색 목록을 만들고 fuse_rrf()가 순위를 합칩니다. 하위 목록의 요청 크기는 max(50, from + size)이며 페이지 자르기는 융합 후에 합니다.

# 기본 RRF: 순위는 1부터, k는 60
최종 점수 = 각 검색 목록의 weight / (60 + 해당 목록에서의 순위)를 합산

문서 A: BM25 1위, 벡터 10위 -> 1/61 + 1/70 ≈ 0.03068
문서 B: BM25 2위, 벡터  2위 -> 1/62 + 1/62 ≈ 0.03226
결과: 두 목록에서 고르게 높은 B가 A보다 앞섭니다.

현재 구현은 하이브리드의 집계 요청과 fusion: learned를 오류로 거절합니다. 같은 파일의 오래된 요약 주석에는 learned 방식의 대체 동작을 암시하는 설명이 남아 있지만, 실제 match 분기는 오류를 반환합니다. 주석 다음에 실행 분기까지 읽어야 하는 사례입니다.

5디렉토리 구조 해부

5-1. 처음 읽는 사람에게 적당한 세 갈래

engine/crates/xerj-engine/src/index.rs는 매우 큰 통합 파일입니다. 처음부터 끝까지 읽기보다 index_batch_turbo, refresh, run_hybrid, fuse_rrf처럼 함수 하나씩 입출력을 적는 방식이 현실적입니다. 인라인 테스트와 구현도 같은 파일 안에 섞여 있습니다.

5-2. 언어별 규모를 읽는 올바른 방법

집계 범위는 커밋 0ccab07의 Git 추적 파일이며, 각 파일의 줄바꿈으로 나눈 물리적 줄 수입니다. 빈 줄·주석·테스트·예제·추적된 생성 파일을 포함합니다. Rust 58.8만 줄을 전부 제품 구현이라고 보거나, HTML 9.4만 줄을 전부 웹 콘솔이라고 해석하면 안 됩니다.

저장소에는 웹 문서와 평가용 자료도 많습니다. 코드 규모는 학습 범위를 가늠하는 정보이지 성숙도나 품질의 점수가 아닙니다. 짧은 함수와 그 함수를 지키는 테스트를 묶어 읽는 것이 더 유익합니다.

6학습 포인트 (기술별)

이 저장소에서 배울 가장 큰 주제는 검색 부품을 연결하면서도 각 부품의 약속을 지키는 방법입니다. 다음 항목은 작은 별도 프로그램으로 옮겨 실험하기 좋습니다.

6-1. Rust: 열거형으로 기능과 실패를 표현하기

Embedder는 선택 가능한 백엔드를 타입으로 드러내고, ReadAdmission은 읽기 허용·쓰기 진행 중·오염 상태를 구별합니다. 문자열 플래그와 true/false만으로 표현할 때보다 빠뜨린 분기를 발견하기 쉽습니다.

6-2. 비동기와 병렬 처리: 기다림이 겹치는가, 계산이 나뉘는가?

하이브리드 검색의 run_hybrid_with_deadline() 주석은 하위 질의의 동시 진행과 CPU의 병렬 실행을 명확히 구분합니다. 임베딩 응답을 기다리는 동안 다른 검색을 진행할 수 있어도, 모든 검색 계산이 서로 다른 코어에서 실행된다는 뜻은 아닙니다.

xerj-autoindex는 동기식 HTTP와 작업 스레드를 사용합니다. “Rust 서버니까 모든 함수가 async일 것”이라는 예상도 맞지 않습니다. 파일 파싱과 CPU 작업을 어느 실행기에서 처리하는지부터 추적해 보세요.

6-3. 정보 검색: 토큰화·점수·후보 집합을 분리하기

RRF는 같은 문서가 두 목록에 나타나면 기여도를 더합니다. 동점일 때의 순서도 결과 재현성에 영향을 주므로, 점수 수식뿐 아니라 최종 정렬 기준까지 읽어 보세요.

6-4. 데이터 공학: 멱등성과 식별자의 한계

engine/crates/xerj-autoindex/src/ids.rs의 doc_id()는 데이터셋 이름, 파일 식별자, 레코드 위치로 ID를 결정합니다. 같은 입력을 다시 보내면 같은 ID를 덮어쓰므로 재시도 때 중복을 줄일 수 있습니다. 이 성질을 멱등성이라고 합니다.

다만 이 파일의 file_key()는 파일 앞 64KiB와 크기로 식별합니다. 같은 크기에서 뒷부분만 바뀌면 이 값만으로는 변경을 증명할 수 없습니다. 전체 증분 동기화는 별도의 상태·세대·내용 검증 코드를 함께 읽어야 합니다. 해시 함수 하나를 보고 전체 변경 감지가 완벽하다고 결론 내리면 안 됩니다.

# ids.rs의 식별자 조합을 설명한 개념식
file_key = hash(파일 앞 64KiB) + 파일 크기
doc_id   = hash("ax1" + 데이터셋 이름 + file_key + 레코드 위치)

같은 레코드 재전송 -> 같은 doc_id -> 중복 생성 대신 같은 대상 갱신

6-5. 파서 설계: 형식마다 다른 레코드 경계

engine/crates/xerj-autoindex/src/extract/mod.rs의 RawRecord는 필드와 locator, 그룹, 필드 출처를 담습니다. CSV 한 행, PDF의 문서 구간, 코드 선언은 서로 다른 단위지만 같은 후속 처리 경로로 보낼 수 있습니다.

특히 FieldOrigin::Data와 FieldOrigin::Extractor를 구분합니다. CSV 헤더처럼 원본에서 나온 필드와, 파서가 추가한 title 같은 필드를 섞으면 파서 개선만으로 데이터셋 분류와 ID가 바뀔 수 있기 때문입니다. 데이터 모델의 “출처”가 재시도 안정성까지 연결되는 사례입니다.

6-6. 시스템 프로그래밍: 파서 실패를 격리하기

engine/crates/xerj-autoindex/src/extract/pdf.rs의 extract()는 spawn_worker()를 통해 별도 프로세스에서 PDF를 읽습니다. 크기·페이지·추출 텍스트·작업 출력을 제한하며, Unix에서는 주소 공간도 제한합니다. 코드 주석도 이것을 충돌과 자원 사용의 격리라고 설명하며 보안 샌드박스라고 부르지 않습니다.

프로세스가 분리돼도 같은 사용자 권한으로 실행된다면 모든 파일 접근이 차단되는 것은 아닙니다. 격리의 목적을 “서버와 함께 죽지 않게 한다”와 “악성 코드를 가둔다”로 나누는 것이 중요한 학습 포인트입니다.

6-7. 테스트: 내부 구조보다 지켜야 하는 성질을 고정하기

engine/crates/xerj-ai/src/local.rs의 lexical_vector_space_is_frozen()은 고정 입력의 벡터 비트와 지문을 검사합니다. 단순히 출력 길이가 384인지 확인하는 것보다 강합니다. 토큰화나 가중치가 바뀌어 기존 벡터와 새 벡터가 섞이는 문제를 잡으려는 테스트입니다.

engine/crates/xerj-mcp/tests/published_schema_drift.rs는 공개 도구 스키마와 서버 도구 정의의 차이를 검사합니다. ES YAML 테스트는 호환 요청의 의미를 검사합니다. 각각 벡터 공간의 안정성, 문서와 제품의 일치, 외부 API 계약이라는 서로 다른 성질을 지킵니다.

7하드웨어 / 시스템 요구사항

7-1. 플랫폼과 CPU

README의 “단일 정적 바이너리”라는 소개를 모든 배포 타깃의 동일한 링크 조건으로 일반화하면 안 됩니다. 릴리스에는 Linux GNU·musl 타깃이 따로 있고 Docker 실행 이미지는 Debian 기반입니다. 소스 빌드 환경도 배포 바이너리의 실행 환경보다 많은 도구와 공간을 요구합니다.

7-2. 메모리 계산은 원본 크기 하나로 끝나지 않는다

원본 파일, 벡터, 검색 자료구조, 모델, 작업 중 버퍼를 각각 더해 용량을 생각해야 합니다. 다음은 압축 전 f32 벡터 본문만의 산술 예시이며, xerj 전체 메모리 실측값이 아닙니다.

벡터 본문 바이트 = 벡터 수 × 차원 수 × 4

100,000개 × 384차원 × 4 = 153,600,000바이트 ≈ 146.5MiB
1,000,000개 × 384차원 × 4 ≈ 1.43GiB

추가 비용: HNSW 연결 + 문서·메타데이터 + 역색인 + WAL·캐시
           + 동시 작업 버퍼 + 선택한 신경망 모델

문서 한 개를 여러 구간으로 나누면 벡터 수가 파일 수보다 많아집니다. 반대로 어휘 검색만 사용하면 신경망 가중치를 메모리에 올릴 필요가 없습니다. README 기준 MiniLM의 약 90MB도 다운로드 자산 규모이며 프로세스 전체 RSS의 상한이 아닙니다.

작은 텍스트 수십 개로 시작해 자료량과 동시 작업 수를 점진적으로 늘리세요. PDF 처리·신경망 모드·큰 로그 입력은 서로 자원 사용 패턴이 다릅니다. 최소 요구 RAM을 하나의 숫자로 확정할 만한 보편적인 근거는 없습니다.

7-3. 설정 파일에 있다고 모두 튜닝 가능한 것은 아니다

engine/xerj.default.toml은 hnsw_m, hnsw_ef_construction, hnsw_ef_search가 이 빌드의 엔진에 연결되지 않았다고 명시합니다. 엔진은 고정 M = 16, 구성 폭 200을 사용하며, 질의 폭은 num_candidates를 받아 최소 800으로 올립니다.

engine/crates/xerj-engine/src/index.rs의 HNSW_MIN_DOCS = 1024와 HNSW_EF_FLOOR = 800도 함께 확인할 수 있습니다. 작은 벡터 집합·필터·일부 벡터 설정에서는 정확 탐색 경로를 사용하므로, 100개짜리 실습으로 HNSW의 성능을 측정했다고 말하면 안 됩니다.

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

실습은 설치된 바이너리와 개인용 로컬 노드를 전제로 합니다. 명령은 학습용 예시이며 결과 수나 실행 시간을 보장하지 않습니다. 각 과제에서 입력·기대 결과·관찰 결과를 남기면 다음 실험의 비교 기준이 됩니다.

xerj autoindex ./xerj-lab/docs --prefix study --dry-run
xerj autoindex ./xerj-lab/docs --prefix study
xerj autoindex map

curl -sS 'http://127.0.0.1:9200/study-*/_search' \
  -H 'Content-Type: application/json' \
  -d '{"query":{"query_string":{"query":"study_unique_42"}},"size":5}'

인증을 켠 노드라면 해당 API 키를 헤더와 CLI 설정에 전달해야 합니다. 실제 생성 인덱스 이름은 데이터 지도에서 확인합니다. 접두사가 같은 다른 실험 자료를 섞지 않는 것이 결과를 해석하기 쉽습니다.

// PUT /study-rag
{"mappings":{"properties":{
  "text":{"type":"text"},
  "vec":{"type":"dense_vector","dims":2,"similarity":"cosine"}
}}}

// 각각 PUT /study-rag/_doc/a, /b, /c 에 넣을 JSON
{"text":"E_CONN_RESET retry budget", "vec":[1.0,0.0]}
{"text":"retry after disconnect",    "vec":[0.7,0.7]}
{"text":"network recovery guide",    "vec":[0.0,1.0]}

// POST /study-rag/_search
{
  "query":{"hybrid":{
    "queries":[
      {"query":{"match":{"text":"E_CONN_RESET"}},"weight":1.0},
      {"query":{"knn":{
        "field":"vec","query_vector":[0.0,1.0],"k":3
      }},"weight":1.0}
    ],
    "fusion":{"type":"rrf","k":60}
  }},
  "size":3
}

임의로 정한 2차원 벡터는 신경망 임베딩이 아닙니다. 벡터의 의미를 사람이 정했기 때문에 거리와 순위를 눈으로 확인할 수 있습니다. 이어서 두 검색의 가중치를 바꾸며 최종 순위가 왜 달라지는지 설명해 보세요.

// MCP 클라이언트 설정 예시: command는 실제 설치 절대 경로
{
  "mcpServers":{
    "xerj":{
      "command":"/absolute/path/to/xerj",
      "args":["mcp"],
      "env":{"XERJ_URL":"http://127.0.0.1:9200"}
    }
  }
}

추가 도전으로 engine/crates/xerj-ai/src/local.rs의 고정 벡터 테스트를 읽고 “차원은 그대로인데 단어 가중치만 바뀌는 경우”를 생각해 보세요. 어떤 식별자를 바꾸고 어떤 자료를 다시 색인해야 할지 설계 메모를 작성하면 데이터 호환성 공부로 이어집니다.

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

Rust 문법부터 분산 시스템까지 한 번에 공부하면 연결 고리를 놓치기 쉽습니다. 작은 검색기를 먼저 이해한 뒤, 입력 형식과 장애 조건을 하나씩 늘리는 순서가 좋습니다. 아래 시간은 학습 계획용이며 숙련도에 따라 조정합니다.

9-1. Rust가 처음이라면 먼저 좁힐 범위

Arc, 원자 연산, 비동기 수명까지 첫 주에 완전히 이해하려 하지 마세요. 처음에는 “입력을 받아 무엇을 반환하는가?”, “실패는 어떤 타입인가?”, “이 함수는 파일·네트워크에 접근하는가?”의 세 질문에 답하면 충분합니다.

2주차에는 외부 검색엔진 없이 작은 역색인을 종이에 만들어도 됩니다. 문서 ID를 정수로 정하고, 단어마다 포함 문서 목록을 만들면 postings가 무엇인지 이해할 수 있습니다. 자료구조의 목적을 안 다음 압축 코드를 읽는 편이 부담이 적습니다.

9-2. 심화 분기: 관심사에 따라 한 가지만 선택

10핵심 키워드 사전

11참고 링크

11-1. 공식 저장소와 제품 문서

• xerj 공식 저장소 · 한국어 README · v1.0.0-rc.98 릴리스
• 아키텍처 지도 · 설계 목적 · 보안 모델
• CLI 문서 · 검색 질의 문서 · 벡터·임베딩 문서
• 에이전트용 안내 · 공개 MCP 도구 스키마
• 측정 절차와 실행기 목록 · 벤치마크 시나리오 · 현장 보고
• 외부 벡터를 쓰는 하이브리드 예제 — 예제의 적용 범위와 현재 내장 기능을 구별해 읽기

11-2. 본문에서 따라간 핵심 소스

• Cargo.toml · Cargo.lock · 설정과 미연결 옵션 주석
• autoindex 처리 단계 · 코드 레코드 추출 · 결정적 ID
• 어휘 해시 임베딩과 고정 벡터 테스트 · 임베딩 백엔드 선택 · 신경망 모델
• BM25 점수 · 색인·refresh·kNN·하이브리드 통합
• WAL 기록·재생·정리 · 읽기 공개 장벽
• MCP 메시지 처리와 도구 · 공개 스키마 차이 검사
• 메모리 API · 실제 권한 검사 · 변환 플러그인과 WASM의 현재 범위
• 콘솔 자산 묶음 · 웹 콘솔 진입점 · CI 정의

11-3. 관련 기술의 1차 자료

• Rust 공식 입문서 · Cargo 기능 선택 문서
• Tokio 공식 학습 자료 · Axum 0.7.9 API
• tree-sitter 공식 문서 · Candle 공식 저장소
• HNSW 원 논문 · RRF 원 논문
• MCP 규격 · JSON-RPC 2.0 규격

현재 상태 (2026-10-23 확인)

GitHub 메타 수치와 최신 릴리스 날짜는 2026-10-23 기준입니다. 의존성·설정·코드 규모·구현 판단은 커밋 0ccab07 기준입니다. 이후 버전의 동작까지 이 표로 단정하지 마세요.

11-4. 설명과 구현이 어긋날 때 확인할 사례

메모리 권한 검사가 있다는 사실 역시 일반적인 다중 사용자 RBAC 전체를 보장하지는 않습니다. engine/crates/xerj-api/src/authz.rs는 예약 메모리 인덱스와 범위가 지정된 키의 경계를 설명하며, 일반 인덱스에 대한 포괄적인 권한 모델에는 남은 범위가 있음을 명시합니다.