jina-grep: Apple Silicon에서 완전히 로컬로 도는 시맨틱 검색 CLI

전통적인 grep 명령어는 수십 년간 개발자들의 필수 도구로 자리해왔지만, 텍스트의 의미를 이해하지 못한다는 근본적인 한계를 지닌다. Jina AI가 2026년 2월 공개한 jina-grep은 바로 이 한계를 돌파하기 위해 설계된 오픈소스 CLI 도구로, Apple Silicon의 MLX 프레임워크를 활용해 완전히 로컬에서 시맨틱 검색을 수행한다. 외부 서버도, 벡터 데이터베이스도 필요 없이 단일 명령어로 자연어 기반 코드 및 텍스트 탐색이 가능해졌다.

왜 기존 grep은 부족했는가

grep -rn "connection" 같은 명령어로 파일을 검색하면, 해당 단어가 포함된 모든 줄을 반환한다. 문제는 "데이터베이스 연결 풀링 로직"을 찾고 싶을 때, pool, connection, db, session 등 다양한 표현이 코드베이스 전체에 산재한다는 점이다. 개발자는 결국 여러 번의 검색을 반복하거나, 코드베이스를 충분히 알고 있어야만 올바른 키워드를 골라낼 수 있다.

이러한 단점은 대규모 코드베이스에서 더욱 두드러진다. 검색어를 모르는 개념을 탐색하거나, 특정 기능의 구현부를 찾거나, 비슷한 패턴의 코드를 찾을 때 키워드 기반 검색은 본질적인 한계를 드러낸다.

jina-grep은 이 문제를 딥러닝 임베딩으로 해결한다. 쿼리와 각 텍스트 줄을 벡터 공간에 매핑하고, 코사인 유사도로 의미적 근접성을 계산하여 관련 결과를 반환한다. 단어가 정확히 일치하지 않아도 의미가 비슷한 코드를 찾아낸다.

동작 모드는 용도에 따라 갈린다

jina-grep은 단순한 단일 모드 도구가 아니라, 여러 동작 모드를 제공하여 다양한 검색 시나리오에 대응한다.

⤢✕

Pipe Mode — grep 출력의 시맨틱 재정렬

가장 단순한 통합 방법이다. 기존 grep 명령어 출력을 파이프로 받아 시맨틱 점수 기준으로 재정렬한다. 기존 grep 워크플로를 그대로 유지하면서 결과의 품질만 개선할 수 있다.

grep -rn "error" src/ | jina-grep "error handling logic"
grep -rn "def.*test" . | jina-grep "unit tests for authentication"
grep -rn "TODO" . | jina-grep "performance optimization"

Standalone Mode — 직접 자연어 파일 검색

grep 없이 jina-grep 단독으로 파일을 탐색하는 모드다. 쿼리와 검색 경로만 지정하면, 디렉토리 전체를 재귀적으로 탐색하며 의미적으로 유사한 줄을 찾아낸다.

jina-grep "memory leak" src/
jina-grep -r --threshold 0.3 "database connection pooling" .
jina-grep --top-k 5 "retry with exponential backoff" *.py

--threshold 옵션으로 유사도 기준을 조정하고, --top-k로 반환할 결과 수를 제한할 수 있다.

Zero-shot Classification — 줄별 레이블 분류

텍스트 각 줄이 어느 카테고리에 해당하는지 분류하는 모드다. 별도의 분류기 학습 없이 레이블 문자열만으로 즉시 동작한다. 로그 분석, 코드 역할 분류, 이슈 트리아지 등에 유용하다.

jina-grep -e "database" -e "error handling" -e "data processing" src/

Code Search Mode — 코드 특화 검색

jina-code-embeddings 모델로 전환하여 코드 특화 검색을 수행한다. 자연어로 코드를 검색하거나(nl2code), 유사한 코드 스니펫을 찾거나(code2code), 코드에 대한 설명을 생성하는(code2nl) 작업에 최적화되어 있다.

jina-grep --model jina-code-embeddings-1.5b --task nl2code "sort a list in descending order" src/
jina-grep --model jina-code-embeddings-0.5b --task code2code "for i in range(len(arr))" src/

어떤 모델을 쓸 것인가

jina-grep은 4개의 MLX 최적화 모델을 제공한다. 각 모델은 용도와 성능 요건에 따라 선택할 수 있다.

모델	파라미터	차원	최대 시퀀스	주요 태스크
jina-embeddings-v5-small	677M	1024	32768	retrieval, text-matching, clustering
jina-embeddings-v5-nano	239M	768	8192	retrieval, text-matching
jina-code-embeddings-1.5b	1.54B	1536	32768	nl2code, code2code, code2nl
jina-code-embeddings-0.5b	0.49B	896	32768	nl2code, code2code

v5 계열은 Matryoshka 표현을 지원하여 임베딩 차원을 동적으로 조정할 수 있다. v5-small은 32~~1024 차원, v5-nano는 32~~768 차원 범위에서 정밀도와 속도를 트레이드오프할 수 있다. 코드 검색 모델은 단일 체크포인트에서 인스트럭션 프리픽스 방식으로 태스크를 전환한다.

모든 모델은 PyTorch나 Transformers 없이 순수 MLX와 Metal GPU 위에서 동작한다. 이는 Apple Silicon의 통합 메모리 아키텍처를 최대한 활용하는 설계다.

M3 Ultra에서 실제로 얼마나 빠른가

M3 Ultra 기준으로 측정한 성능 수치는 실사용에 충분히 빠르다. v5-small 모델은 쿼리당 7ms, 피크 처리량 25,300 토큰/초를 기록한다. v5-nano는 더 가벼운 처리를 원할 때 선택할 수 있다.

실행 방식은 두 가지다.

Serverless 모드(기본값): 모델을 프로세스 내에 로드하고 쿼리를 처리한 뒤 종료한다. 별도의 서버 프로세스가 없어 스크립트나 CI 파이프라인에서 사용하기 적합하다. macOS는 MLX가 mmap으로 로드한 가중치를 페이지 캐시에 유지하므로, 재실행 시 디스크 I/O 없이 빠르게 모델을 로드한다.

Persistent Server 모드: 백그라운드 서버를 유지하여 모델을 GPU 메모리에 상주시킨다. 쿼리당 약 10ms의 일정한 응답 시간을 제공한다. 인터랙티브 세션이나 배치 작업에 적합하다.

jina-grep serve start    # 서버 시작
jina-grep "query" src/   # 서버 감지 시 자동으로 HTTP 경유
jina-grep serve stop     # 서버 종료

Serverless 모드는 실행 시 자동으로 서버 존재를 감지하며, 서버가 있으면 HTTP를 통해 통신한다.

설치하고 바로 써보기

git clone https://github.com/jina-ai/jina-grep-cli.git && cd jina-grep-cli
uv venv .venv && source .venv/bin/activate
uv pip install -e .

요구 사항은 Python 3.10 이상과 Apple Silicon Mac이다. M1/M2/M3/M4 계열의 모든 칩에서 동작하며, Intel Mac은 지원하지 않는다. 이는 MLX 프레임워크가 Apple Silicon의 통합 메모리와 Metal GPU에 특화되어 있기 때문이다.

jina-cli 패키지를 별도로 설치하면 jina grep 명령어로도 동일한 기능을 사용할 수 있다. jina-cli는 웹 검색, 임베딩 생성, 리랭크 등 Jina AI API 전체를 Unix 파이프 스타일로 사용할 수 있는 통합 CLI 도구다.

grep과 무엇이 다르고, 언제 grep을 쓰나

jina-grep은 기존 grep을 대체하기보다는 보완하는 도구다. 정확한 패턴 매칭이나 정규식 검색은 여전히 grep이 더 빠르고 정확하다. 반면 의미 기반 탐색, 특히 검색어를 정확히 모르는 상황에서 개념 단위로 코드를 찾거나, 문서에서 관련 내용을 탐색하는 작업에서는 jina-grep이 압도적으로 유리하다.

Pipe Mode는 이 두 도구의 강점을 결합하는 가장 실용적인 방법이다. grep으로 후보 집합을 빠르게 필터링하고, jina-grep으로 의미 기반 재정렬을 수행하는 2단계 파이프라인은 속도와 품질을 모두 잡는 접근이다.

jina-grep은 "로컬 AI" 트렌드의 실용적인 사례이기도 하다. 거대한 벡터 데이터베이스 인프라나 클라우드 API 없이, 개발자 노트북에서 곧바로 시맨틱 검색을 수행할 수 있다는 점은 개발 워크플로에 직접 통합할 수 있는 가능성을 열어준다. Apple Silicon의 통합 메모리 아키텍처와 MLX의 Metal GPU 최적화가 결합된 덕분에, 수백 MB짜리 임베딩 모델이 실용적인 지연 시간 내에 동작한다.