Get started · Gemstone Guide

Requirements

준비물

Git, Python 3.13 for upstream PyTorch or free-threaded 3.15t for torchnative, and uv. uv can install either one for you.
Git, upstream PyTorch 용 Python 3.13 또는 torchnative 용 free-threaded 3.15t, uv. 둘 다 uv 가 설치해 줍니다.
JDK 21 or newer for the Kotlin client.
Kotlin 클라이언트용 JDK 21 이상.
No GPU is needed: the engine runs on the CPU, and the default model, Qwen 3 0.6B, is small enough for it. GPU (CUDA) support is planned (#164).
GPU 는 필요 없습니다. 엔진은 CPU 에서 돌고, 기본 모델인 Qwen 3 0.6B 는 CPU 로 충분할 만큼 작습니다. GPU(CUDA) 지원은 계획 단계입니다(#164).
Xcode, for iOS only.
iOS 에만 Xcode.

1. Install the server

1. 서버 설치

git clone https://github.com/LogitAI/Gemstone.git
cd Gemstone
uv sync --python 3.13 --extra torch

That installs upstream PyTorch. To use torchnative instead, run uv sync --python 3.15t --extra torchnative. The two extras cannot be installed together, because torchnative replaces import torch.

이렇게 하면 upstream PyTorch 가 설치됩니다. 대신 torchnative 를 쓰려면 uv sync --python 3.15t --extra torchnative 를 실행하세요. 두 extra 는 함께 설치할 수 없습니다. torchnative 가 import torch 를 대체하기 때문입니다.

On torchnative 0.1.0b6 generation does not work yet. Its torch._C shim lacks triu_ (used by transformers continuous batching), nansum (typical_p) and Generator.get_state, and importing it re-enables the GIL on 3.15t. torchnative is fixing these, tracked on #177. Until then, chat on upstream PyTorch.

torchnative 0.1.0b6 에서는 아직 생성이 동작하지 않습니다. 그 torch._C shim 에 triu_(transformers 연속 배칭이 씀), nansum(typical_p), Generator.get_state 가 없고, import 하면 3.15t 에서 GIL 이 다시 켜집니다. torchnative 가 이를 고치는 중이며 #177 에서 추적합니다. 그때까지는 upstream PyTorch 로 채팅하세요.

2. Start it

2. 실행

uv run --extra torch python -m api run server                  # 127.0.0.1:23100 (loopback only)
uv run --extra torch python -m api run server 127.0.0.1 23100  # explicit host and port

uv run uses the environment uv sync created, so there is no virtual environment to activate. Use --extra torchnative if you installed that one. Logs go to the console at INFO; set GEMSTONE_LOG_LEVEL=DEBUG to also log prompts and answers.

uv run 은 uv sync 가 만든 환경을 쓰므로 가상환경을 따로 활성화할 필요가 없습니다. torchnative 를 설치했다면 --extra torchnative 를 쓰세요. 로그는 INFO 수준으로 콘솔에 나가며, GEMSTONE_LOG_LEVEL=DEBUG 를 설정하면 프롬프트와 답변도 기록합니다.

The model downloads from Hugging Face the first time a session uses it, once. Qwen 3 0.6B is about 1.5 GB (its model.safetensors on the Hub).

모델은 세션이 처음 사용할 때 Hugging Face 에서 한 번 내려받습니다. Qwen 3 0.6B 는 약 1.5 GB 입니다(Hub 의 model.safetensors 기준).

3. Open a client

3. 클라이언트 열기

The quickest is the web client the server already bundles: open http://127.0.0.1:23100/. For a native window:

가장 빠른 것은 서버에 이미 들어 있는 웹 클라이언트입니다: http://127.0.0.1:23100/ 를 여세요. 네이티브 창은:

./gradlew :app:run           # desktop
./gradlew :app:installDebug  # Android

Clients look for the server at 127.0.0.1:23100. To use one on another machine, start the server with GEMSTONE_HOST=0.0.0.0 and a GEMSTONE_API_KEY (Run the server), then see Connect clients.

클라이언트는 127.0.0.1:23100 에서 서버를 찾습니다. 다른 머신의 서버를 쓰려면 GEMSTONE_HOST=0.0.0.0 과 GEMSTONE_API_KEY 로 서버를 띄운 뒤(서버 운영) 클라이언트 연결을 보세요.

If something goes wrong

문제가 생기면

ModuleNotFoundError from a bare python -m api run server means that is the system Python, not the synced environment: start it with uv run --extra torch as above.
그냥 python -m api run server 에서 ModuleNotFoundError 가 나면 동기화된 환경이 아니라 시스템 Python 인 것입니다: 위처럼 uv run --extra torch 로 실행하세요.

From clone to first answer

클론부터 첫 답변까지