설치

<!-- translations:start -->

English · 中文 · 日本語 · Русский · Español · Français · Deutsch

<!-- translations:end --> Tesserae는 PyPI에 게시되어 있으며, 사용자가 python3 -m tesserae.cli를 직접 실행하지 않아도 되도록 셸 명령을 제공합니다.

PyPI에서 설치 (권장)

pip install tesserae

이것으로 끝입니다. pip가 PATH에 두 개의 콘솔 스크립트를 등록합니다:

tesserae --help
tesserae_mcp --help

문서에서의 표준 명령은 tesserae입니다. tesserae_mcp는 MCP 서버를 시작합니다(이제 온디맨드 compile_context 도구를 노출합니다 — Quickstart 참조).

pipx도 좋습니다. CLI 도구를 각자의 격리된 venv에 두는 것을 선호한다면:

pipx install tesserae

uv도 되지만, extra는 따옴표 안에 넣어야 합니다. uv tool install에는 --extra 플래그가 없어서(uv 0.10 기준 확인), uv tool install tesserae --extra semantic은 unexpected argument '--extra'로 종료되고 extra는 결국 설치되지 않습니다:

uv tool install "tesserae[semantic]"        # extra는 따옴표 안에
uv tool install --with model2vec tesserae   # 동일한 효과

스크립트로 실행한다면 종료 코드를 확인하세요. semantic 설치가 조용히 건너뛰어지는 것이 바로 hybrid retrieval과 associate가 비시맨틱 스텁으로 강등되는 원인입니다.

업그레이드

pip install --upgrade tesserae

머신 전역 설정 (한 번 설정, 모든 프로젝트)

프로젝트별 설정 대신 Tesserae를 한 번만 설정하고, 선택적 의존성을 하나의 명령으로 설치하세요:

# Interactive machine-wide setup — pick LLM provider/effort + which deps to install:
tesserae setup
# …or non-interactively (written to ~/.tesserae/config.json) + install everything:
tesserae setup --llm-provider codex --reasoning-effort medium --install all

# Just see / manage optional dependencies
tesserae config deps                     # show what's installed
tesserae config deps --install memex     # fast transcript search (needs cargo)

알려진 선택적 의존성: memex (빠른 트랜스크립트 검색)와 raganything. 프로젝트별 .tesserae/config.json은 여전히 이 글로벌 기본값을 재정의합니다(해석 순서: env → project → global → built-in). tesserae init도 대화형 설정 중에 memex 설치를 제안합니다.

선택적 통합 (프로젝트별)

기본 wheel은 의도적으로 가볍고, 선택적 메모리 백엔드는 기본적으로 꺼져 있습니다. tesserae init이 프로젝트별 온보딩의 유일한 단계입니다 — 그 마법사가 LLM 프로바이더와 감지된 소스를 선택합니다; 더 무거운 컴패니언/런타임 구성 요소는 tesserae setup --install …(또는 tesserae config deps --install …)로 머신 전역에 설치하고 프로젝트별로 .tesserae/config.json에서 활성화합니다:

# Machine-wide installs of the optional pieces:
tesserae setup --install raganything

# Then per project: enable what you want in .tesserae/config.json
#   memory_backends.raganything.enabled: true   (query via `tesserae query --backend raganything`)

고급 워크플로를 위한 수동 패키지 설치도 여전히 가능합니다:

pip install kuzu graphiti-core

• kuzu — Kuzu 그래프 영속화.
• RAG-Anything — pip install 'raganything[all]'로 설치(tesserae setup --install raganything); Tesserae는 멀티모달 파서 실행을 위한 관리형 refresh 래퍼를 저장합니다.
• graphiti-core — 라이브 Graphiti/Neo4j 동기화. export graphiti와 export graphiti --sync --dry-run은 이것 없이도 동작합니다.

Anthropic 기반 synthesis 경로는 extras 마커를 사용합니다:

pip install "tesserae[synthesis-llm]"

실제 시맨틱 embedding(v0.5.0부터 기본 retrieval 레인)은 semantic extra 뒤에 제공됩니다:

pip install "tesserae[semantic]"

이는 model2vec을 가져오고 가볍고 오프라인이며 torch가 필요 없는 정적 모델(~8 MB potion-base-8M, 첫 사용 시 한 번 다운로드)을 내려받습니다. 이것이 없으면 hybrid/embedding retrieval은 비시맨틱 hash-bucket 스텁으로 폴백하고 큰 경고를 출력하므로, tesserae ask, tesserae context, 또는 MCP compile_context 도구를 사용하는 모든 사용자에게 이 extra 설치를 권장합니다.

모든 파서가 사전 설치된 멀티모달 RAG-Anything 스택은:

pip install 'tesserae[raganything-all]'

시스템 사전 요구사항: .doc/.docx/.ppt/.pptx/.xls/.xlsx 파싱에는 호스트에 LibreOffice가 필요합니다. 플랫폼의 패키지 매니저로 설치하세요(예: brew install --cask libreoffice, apt-get install libreoffice); LibreOffice가 없으면 RAG-Anything은 경고와 함께 Office 문서를 건너뜁니다.

소스에서 설치 (기여자용)

코드베이스를 직접 수정하고 싶다면 editable 체크아웃을 설치하세요:

git clone https://github.com/ca1773130n/Tesserae.git
cd Tesserae
pip install -e .

편의 설치 스크립트도 번들되어 있습니다 — 클론하고, 프로젝트 로컬 .venv를 만들고, pip install -e .를 실행하고, 래퍼를 ~/.local/bin에 배치합니다:

# Quick: clone + install in one shot
curl -fsSL https://raw.githubusercontent.com/ca1773130n/Tesserae/main/scripts/install.sh | bash

# From an existing checkout
./scripts/install.sh --dir "$PWD"

유용한 플래그 (./scripts/install.sh --help):

--skip-shell-config를 사용했다면, 셸을 재시작하거나 다음을 실행하세요:

export PATH="$HOME/.local/bin:$PATH"

설치 확인

tesserae init --help
tesserae compile --help
tesserae export site --help