NNexithDocs
상태대시보드 ↗
개요 및 빠른 시작모델 카탈로그가이드API 레퍼런스연동OAuth2 / OIDC

스트리밍 프로토콜

적용 대상: /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] 종료, 빈 줄 하트비트를 처리해야 합니다.
  • 끊김 재시도: 텍스트 스트림은 이어받기가 없으므로 재시도하면 새 과금 요청이 발생합니다. 작업 스트림은 안전하게 재연결할 수 있습니다.