스트리밍 프로토콜
적용 대상:
/v1/chat/completions,/v1/responses,/v1/messages,/v1/jobs/:id/events
Nexith의 스트리밍 응답은 모두 text/event-stream(SSE)입니다. 텍스트 생성은 OpenAI 호환
chat.completion.chunk 프레임을 사용하고, 이미지 작업은 작업 이벤트 프레임을 사용합니다. 또한 소수의 nexith.* 사이드 채널 프레임이 있으며,
호출자가 해당 nexith_* 확장을 명시적으로 켰을 때만 나타납니다.
1. 텍스트 스트림(Chat Completions)#
요청#
{
"model": "nexith-core",
"messages": [{"role": "user", "content": "写一首短诗"}],
"stream": true,
"stream_options": {"include_usage": true}
}프레임 형식#
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1795055220,"model":"nexith-core","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}
data: {"id":"chatcmpl-...","object":"chat.completion.chunk",...,"choices":[{"index":0,"delta":{"content":"春"},"finish_reason":null}]}
data: {"id":"chatcmpl-...","object":"chat.completion.chunk",...,"choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: {"id":"chatcmpl-...","object":"chat.completion.chunk",...,"choices":[],"usage":{"prompt_tokens":12,"completion_tokens":34,"total_tokens":46}}
data: [DONE]핵심 사항:
data: <json>\n\n형식으로 전송하고, 마지막에 항상data: [DONE]을 보냅니다.stream_options.include_usage=true이면[DONE]전에choices: []+usage프레임이 하나 있으며, 과금은 이 프레임을 기준으로 합니다. 전달하지 않으면 사용량 프레임이 없습니다(OpenAI의 이전 동작).- 도구 호출은
delta.tool_calls증분으로 전송되며, 병합 규칙은 OpenAI와 동일합니다. - 연결은 서버가 유지하며(SSE comment 하트비트), 프록시 타임아웃은 보통 300s입니다.
오류#
- 첫 token 이전 실패: 정상적인 HTTP 오류(4xx/5xx + JSON body)를 반환하며, 먼저 200을 보내지 않습니다.
- 출력이 시작된 이후 실패: 상태 코드를 바꿀 수 없으므로, 스트림 안에 오류 객체 프레임을 하나 보낸 뒤 종료합니다. 클라이언트는 이미 받은 내용을 불완전한 것으로 간주해야 합니다.
2. 사이드 채널 프레임(Nexith 확장)#
요청에 해당 스위치가 포함된 경우에만 나타납니다. 순수 OpenAI 클라이언트는 이 프레임들을 받지 않습니다.
nexith.sources(웹 검색 출처)#
답변 첫 프레임 이전에 전송되어, 프런트엔드가 인용 카드를 먼저 렌더링할 수 있게 합니다:
{
"object": "nexith.sources",
"sources": [
{"title": "…", "url": "https://…", "content": "摘要片段"}
]
}nexith.step(심층 연구 진행 상황)#
심층 연구의 각 단계(계획, 검색, 수집, 압축)를 프레임 단위로 재생하며, nexith.sources 앞에 위치합니다:
{"object": "nexith.step", "label": "检索", "model": "…", "content": "…", "items": [...]}nexith.image_request(이미지 생성 의도)#
요청에 nexith_detect_media: true가 있고 L1이 이미지 생성 의도로 판정하면, 게이트웨이는 텍스트 스트림으로 진입하지 않고
비스트리밍 JSON을 직접 반환합니다:
{
"object": "nexith.image_request",
"capability": "image.generate",
"target_model": "nexith-image",
"original_prompt": "画一只小猫",
"enhanced_prompt": "A cute kitten, …",
"size": "1024x1024"
}프런트엔드는 이를 받으면 POST /v1/images/generations를 호출해 비동기 작업을 제출해야 합니다. 이미지 편집 의도는
nexith.image_edit_request에 대응합니다(추가로 참조 이미지 정보 포함).
nexith.routing_decision(Responses 어댑터 계층)#
/v1/responses는 호출자가 능력을 보완해야 할 때 이 구조(status=requires_capability)를 반환할 수 있으며,
클라이언트에게 "이런 요청에는 어떤 능력 등급이 필요한지" 알려 주는 용도이지 텍스트 답변을 위조하는 것이 아닙니다.
3. 비스트리밍 응답의 nexith 객체#
비스트리밍 Chat Completions 응답 본문에는 최상위 nexith 객체가 포함될 수 있습니다(마찬가지로 확장을 켰을 때만):
{
"id": "chatcmpl-...",
"object": "chat.completion",
"choices": [...],
"usage": {...},
"nexith": {
"memory": [{"id": "...", "content": "...", "score": 0.83}],
"sources": [{"title": "...", "url": "...", "content": "..."}],
"steps": [{"label": "...", "model": "...", "content": "..."}]
}
}필드는 모두 선택 사항입니다: return_memory → memory; nexith_web_search → sources;
nexith_deep_research → steps.
4. 작업 이벤트 스트림(Jobs SSE)#
GET /v1/jobs/:id/events는 작업 이벤트 스트림을 반환하며, 프레임 형식은 텍스트 스트림과 다릅니다:
data: {"event":"queued","payload":{},"ts":"2026-11-19T02:00:00Z"}
data: {"event":"started","payload":{},"ts":"..."}
data: {"event":"completed","payload":{},"ts":"..."}- 이벤트 유형:
queued/started/error/completed/failed/cancelled. - 각 연결은 이벤트 0부터 재생되므로, 클라이언트는 재연결만 하면 전체 기록 이벤트를 채울 수 있습니다.
- 서버는 15초마다 SSE comment 하트비트를 보내 프록시의 유휴 연결 끊김을 방지합니다.
error/failed의payload.error는 불투명한 고정 문구이며 업스트림 모델 이름이나 내부 오류 원문을 포함하지 않습니다.completed/failed/cancelled를 받으면 서버가 스트림을 종료합니다.
5. 클라이언트 권장 사항#
- 공식 SDK를 사용할 때는 SSE를 직접 파싱하지 말고
stream=true를 그대로 사용하세요. - 자체 클라이언트는 chunk 경계를 넘는 반쪽 프레임,
[DONE]종료, 빈 줄 하트비트를 처리해야 합니다. - 끊김 재시도: 텍스트 스트림은 이어받기가 없으므로 재시도하면 새 과금 요청이 발생합니다. 작업 스트림은 안전하게 재연결할 수 있습니다.