Streaming protocol · Gemstone Guide

Endpoints

엔드포인트

Method메서드	Path경로	Purpose용도
GET	`/api/models`	List models모델 목록
POST	`/api/models/{id}/sessions/`	Create a session → `session_id`세션 생성 → `session_id`
DELETE	`/api/sessions/{session_id}`	Close a session; the model stays loaded until its keep_alive (5 minutes) ends세션 종료. 모델은 keep_alive(5분)가 끝날 때까지 올라가 있음
WS	`/api/chat/streaming`	Streaming chat스트리밍 채팅

The same server also speaks the Ollama API (/api/chat, /api/generate, /api/tags, /api/pull, /api/ps and more), so Ollama clients can connect to it directly. That API passes tool calls back to the client instead of running them.

같은 서버는 Ollama API(/api/chat, /api/generate, /api/tags, /api/pull, /api/ps 등)도 제공하므로 Ollama 클라이언트가 바로 연결할 수 있습니다. 이 API 는 도구 호출을 실행하지 않고 클라이언트에 그대로 돌려줍니다.

The conversation

대화

After the socket opens, send exactly three text frames:

소켓이 열리면 정확히 세 개의 텍스트 프레임을 보냅니다:

{"session_id": "qwen3_20260614125444"}
[{"role": "user", "content": "Hi"}, {"role": "assistant", "content": "Hello!"}]
What is the weather in Daejeon today?

Then read text frames until <EOS>. Plain frames are answer text. Three kinds of frame are special:

그다음 <EOS> 까지 텍스트 프레임을 읽습니다. 일반 프레임은 답변 텍스트이고, 세 종류가 특별합니다:

Frame프레임	Meaning의미
`<think>` / `</think>`	Reasoning starts / ends; frames between are the model's thoughts추론 시작 / 끝. 사이의 프레임은 모델의 생각
`<tool_call>…</tool_call>`	A JSON tool record (below)JSON 도구 레코드 (아래)
`<EOS>`	The answer is complete; the server closes the socket답변 완료. 서버가 소켓을 닫음

Tool records

도구 레코드

{"call":   {"id": "call_20250614125444", "function": {"name": "get_weather", "arguments": {"location": "Daejeon"}}}}
{"result": {"id": "call_20250614125444", "function": {"name": "get_weather", "content": "<cached_result:call_20250614125444>"}}}
{"history": [ {"role": "assistant", "content": "", "tool_calls": [ … ]}, {"role": "tool", "tool_call_id": "…", "content": "<cached_result:…>"} ]}

Append the history messages to your own history and send them back next turn. The server keeps the real tool output; the client only sees the <cached_result:…> placeholder.

history 메시지를 내 기록에 붙여 다음 턴에 다시 보냅니다. 실제 도구 출력은 서버가 들고 있고, 클라이언트는 <cached_result:…> 자리표시자만 봅니다.

Errors

오류

Unknown session on the socket: closed with code 1008.
소켓에서 모르는 세션: 코드 1008 로 닫힙니다.
Unknown model or unknown session on the HTTP routes: HTTP 404 with a JSON detail.
HTTP 경로에서 모르는 모델이나 모르는 세션: HTTP 404 와 JSON detail 을 돌려줍니다.
A model that must be downloaded but cannot be (offline, or the download failed): closed with code 1011 and a reason that says what to do.
내려받아야 하는 모델을 받을 수 없을 때(오프라인이거나 다운로드 실패): 코드 1011 로 닫히고, 이유에 해야 할 일이 적힙니다.
The model stays busy past its timeout (GEMSTONE_QUEUE_TIMEOUT or GEMSTONE_LOAD_TIMEOUT): closed with code 1013, so that the client can try again later.
모델이 제한 시간(GEMSTONE_QUEUE_TIMEOUT 또는 GEMSTONE_LOAD_TIMEOUT)이 지나도록 사용 중일 때: 코드 1013 으로 닫힙니다. 클라이언트가 나중에 다시 시도할 수 있게 하기 위해서입니다.

Build on the streaming protocol

스트리밍 프로토콜 위에 만들기