AI Connections용 Streaming Responses

AI 앱의 실제 출력을 HTTP Streaming 또는 SSE로 스트리밍하는 기능이에요.

출처: 문서

본문

개요 (Overview)

AI 앱이 응답을 한 번에 다 반환하지 않고 스트리밍한다면, AI Connection을 그 스트림을 읽도록 구성할 수 있어요. Confident AI는 기본 단일 샷(single-shot) HTTP Response 외에 두 가지 스트리밍 응답 모드를 지원해요.

HTTP Streaming — 엔드포인트가 줄바꿈으로 구분된 청크 스트림(NDJSON)을 반환.
SSE Streaming — 엔드포인트가 Server-Sent Events(text/event-stream) 스트림을 반환.

AI connection의 AI App Endpoint 섹션에서 모드를 선택해요. Confident AI는 각 청크가 도착할 때마다 읽고, actual output(선택적으로 retrieval context, tools called, state)을 추출한 다음 최종 결과를 조립해요.

기본 모드는 HTTP Response예요. 엔드포인트가 실제로 스트리밍하는 경우에만 스트리밍 모드로 전환하세요.

청크 형식 (Chunk Formats)

HTTP Streaming과 SSE Streaming 모두에서 각 청크는 일반 문자열, JSON 객체, 또는 트랜스포머나 키 경로로 추출하는 커스텀 형식일 수 있어요.

문자열 (Strings)

문자열 청크의 경우 Confident AI는 모든 청크를 모아 하나의 문자열로 결합해요.

모델이 스트리밍하면:

["Hello", " world", "!"]

Confident AI가 반환하는 결과:

"Hello world!"

JSON

JSON 객체의 경우 Confident AI가 각 청크를 파싱하고 추출된 값을 최종 출력으로 결합해요.

모델이 스트리밍하면:

[{ "chunk": "Hello" }, { "chunk": " world" }, { "chunk": "!" }]

Confident AI가 반환하는 결과:

"Hello world!"

와이어(wire) 상에서 두 스트리밍 모드가 어떻게 다른지 보여줄게요.

HTTP Streaming — 한 줄에 하나의 JSON 객체(또는 문자열)를 보내요. application/x-ndjson이 권장 Content-Type이에요. 비어 있지 않은 각 줄은 독립적으로 파싱돼요.
SSE Streaming — text/event-stream으로 표준 data: 프레임을 보내고, data: [DONE]으로 스트림을 끝내요. 각 data: 페이로드는 JSON으로 파싱돼요.

SSE 이벤트 (SSE Events)

Server-Sent Events는 각 프레임에 이벤트 이름(event: 필드)을 담을 수 있어요. 이 덕분에 단일 스트림이 증분 출력 토큰, 검색 소스, 도구 호출, state 같은 다른 종류의 데이터를 개별적으로 이름 붙은 이벤트로 섞어 보낼 수 있어요. SSE 연결에서는 각 필드를 나르는 이름 붙은 이벤트가 무엇인지 Confident AI에 알려줄 수 있어요.

이벤트 이름과 accumulate 모드는 SSE Streaming에만 적용돼요. HTTP Streaming은 이름 붙은 이벤트 개념이 없어요. 모든 청크가 actual output에 기여해요.

이벤트 이름 지정하기 (Specifying Event Names)

AI connection의 Output parsing 탭에서 각 필드에 SSE Event Name 입력이 있어요.

Actual Output — 선택. 비워 두면 모든 프레임에서 출력을 읽고, 설정하면(예: last_message) 해당 이벤트의 프레임에서만 출력을 읽어요.
Retrieval Context, Tools Called, State — SSE에서 필수. actual output과 달리 이 값들은 프레임을 가로질러 누적할 수 없어서, 여기서 이름 붙인 이벤트의 마지막 프레임에서 읽어요.

이벤트 누적 (Accumulate Events)

Accumulate Events 토글(actual output 전용, SSE 전용)은 출력 프레임을 어떻게 결합할지 제어해요.

On (기본값) — 출력 이벤트의 모든 프레임을 연결해 최종 값을 만든다. 서버가 증분 델타(예: 토큰 단위)를 스트리밍하고 완전한 최종 스냅샷을 보내지 않을 때 켜요.
Off — 각 프레임이 이전 프레임을 대체한다 (마지막 프레임이 승리). 마지막 프레임에 전체 출력이 이미 담겨 있을 때 사용해요.

SSE 이벤트를 하나도 지정하지 않으면 Confident AI는 기본적으로 모든 프레임의 출력을 누적해요. 일반 문자열·JSON 스트리밍과 동일해요.

예시 (Example)

이런 SSE 스트림이 있다고 해볼게요.

event: token
data: {"delta": "Hello"}

event: token
data: {"delta": " world"}

event: last_message
data: {"answer": "Hello world", "sources": ["doc-1", "doc-2"]}

data: [DONE]

최종 출력 "Hello world"를 추출하는 방법은 두 가지예요.

델타 누적 — Actual Output SSE Event Name을 token으로, Accumulate Events를 켜고, Actual Output Key Path를 ["delta"]로 설정. Confident AI가 "Hello" + " world"를 연결해요.
최종 스냅샷 읽기 — Actual Output SSE Event Name을 last_message로, Accumulate Events를 끄고, Actual Output Key Path를 ["answer"]로 설정. 마지막 last_message 프레임에서 전체 답변을 읽어요.

검색 컨텍스트도 캡처하려면, Retrieval Context SSE Event Name을 last_message로, 그 키 경로를 ["sources"]로 설정해요. 해당 이벤트의 마지막 프레임에서 읽혀요.

다음 단계 (Next Steps)

스트리밍을 구성했으니, 이제 인증과 트레이스 연결로 AI connection 설정을 마무리해 보세요.

Authorization

시크릿 매니저와 Auth0 또는 HMAC 인증으로 요청을 보호해요.

Linking Traces

테스트 케이스와 턴을 그 트레이스에 연결해 완전한 관측성을 확보해요.

더 알아보기 (Learn more)

Authorization