스트리밍이 제공하는 것
스트리밍 없이 API는 모델이 완료될 때까지 전체 답변을 유지한 후 하나의 JSON 바디로 전송합니다. 긴 응답의 경우 화면이 몇 초 동안 비어 있을 수 있습니다. stream: true를 사용하면 서버는 동일한 답변을 작은 이벤트 시리즈로 전송하며, 각 이벤트는 응답의 일부 문자를 포함하고 UI는 도착하는 대로 이를 출력할 수 있습니다.
와이어 형식은 일반 HTTP 응답을 통한 서버 전송 이벤트(SSE)입니다. 각 이벤트는 data:로 시작하는 줄과 JSON 청크로 구성되며, 스트림은 data: [DONE]로 끝납니다. OpenAI SDK가 이를 처리하므로 수동으로 파싱할 일이 거의 없습니다. 원시 바이트를 확인하려면 개발자 개요에서 엔드포인트 레이아웃을 확인하고 API 문서에서 모든 매개변수를 확인할 수 있습니다.
코드를 작성하기 전에 결정해야 할 두 가지 사항이 있습니다. 먼저 스트림을 읽는 주체는 무엇인지입니다: 귀하의 서버와 통신하는 브라우저인지, 아니면 귀하의 서버만인지입니다. 두 번째는 연결이 중간에 끊겼을 때 어떻게 처리할지입니다. 이 페이지의 나머지 부분에서는 이 두 가지 모두를 다룹니다.
Python: OpenAI SDK로 스트리밍
pip install openai로 SDK를 설치하고, 기본 URL을 사용하여 클라이언트를 생성한 후 stream=True를 전달하세요. 모델 ID는 uncensored입니다.
from openai import OpenAI
client = OpenAI(
base_url="https://api.uncensoredllmapi.com/v1",
api_key="YOUR_KEY",
)
stream = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Write a four-line poem about rain."}],
stream=True,
)
text = []
usage = None
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
piece = chunk.choices[0].delta.content
text.append(piece)
print(piece, end="", flush=True)
if getattr(chunk, "usage", None):
usage = chunk.usage
print()
print("tokens:", usage)
chunk.choices and ... 가드를 확인하세요. 사용량 정보를 담는 마지막 청크는 빈 choices 목록을 가질 수 있으며, 여기에 접근하면 오류가 발생합니다. 조각들을 목록에 모아서 나중에 연결하는 것은 긴 응답에서 반복적인 문자열 결합보다 비용이 적게 듭니다.
Node: JavaScript에서의 동일한 호출
Node용 공식 openai 패키지에서 스트림은 비동기 반복기입니다. 이 예제는 ES 모듈을 사용합니다.
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.uncensoredllmapi.com/v1",
apiKey: process.env.API_KEY,
});
const stream = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "user", content: "Name three uses for a stream." }],
stream: true,
});
let full = "";
let usage = null;
for await (const chunk of stream) {
const piece = chunk.choices?.[0]?.delta?.content;
if (piece) {
full += piece;
process.stdout.write(piece);
}
if (chunk.usage) usage = chunk.usage;
}
console.log("\nusage:", usage);
SDK를 사용하지 않으려면 fetch도 사용할 수 있습니다: stream: true와 함께 동일한 JSON 본문을 보내고, TextDecoder로 response.body를 읽은 후 공백 줄에서 분할하세요. SDK는 청크 경계에서 이벤트가 잘리는 일반적인 버그를 처리하지 않아도 되도록 도와줍니다.
사용량 및 잔액 읽기
사용량은 스트림 끝에 보고됩니다. 비용 추적을 위해 로그에 기록해야 할 숫자입니다. 이는 잔액이 차감되는 기준이기 때문입니다. 입력 토큰 1M당 $0.15, 출력 토큰 1M당 $0.50으로, 입력 토큰 1,200개와 출력 토큰 800개로 구성된 응답의 비용은 1,200 x 0.15 / 1,000,000 + 800 x 0.50 / 1,000,000 = $0.00018 + $0.0004 = $0.00058입니다.
모든 응답에는 잔여 크레딧을 나타내는 X-Balance-USD 헤더가 포함되어 있으므로 두 번째 요청 없이 낮은 잔액 경고를 표시할 수 있습니다. 또한 GET /v1/balance을 정해진 시간 간격으로 호출할 수도 있습니다. 실패하거나 거부된 요청에는 요금이 부과되지 않으므로, 첫 번째 토큰 전에 오류가 발생하면 비용이 들지 않습니다.
동일한 응답 헤더에는 X-Request-Id가 포함됩니다. 각 스트림의 로깅 줄 옆에 저장하세요. 스트림이 이상하게 동작할 경우, 해당 ID를 지원팀에 제공하여 요청을 찾을 수 있습니다.
스트림 손실 및 대응 방법
스트림은 끊어질 수 있습니다. 전화기가 Wi-Fi에서 모바일 데이터로 전환되거나, 프록시가 유휴 연결을 닫거나, 사용자가 탭을 닫을 수 있습니다. 처음부터 이에 대비하세요.
부분 텍스트 유지
각 조각이 도착할 때마다 버퍼에 추가하고, 루프가 종료되거나 예외가 발생하면 버퍼를 저장합니다. 스트림이 실패했다면 사용 가능한 반쪽 응답을 얻게 됩니다. 이를 삭제하지 말고 재시도 버튼으로 표시하세요.
재시도 또는 계속
가장 간단한 복구 방법은 원래 요청을 다시 보내는 것입니다. 짧은 응답이라면 문제가 없습니다. 긴 응답의 경우 저장된 부분 텍스트를 어시스턴트 메시지로 보내고 모델이 중단된 지점부터 계속 생성하도록 요청할 수 있습니다. 결과가 첫 번째 스트림이 생성했을 내용과 일치하지 않을 수 있으므로 최선 방식으로 간주하고, 정확성이 중요하다면 UI에 라벨을 붙이세요.
포기된 스트림 닫기
스트리밍 요청은 스트림이 끝날 때까지 동시성 슬롯을 점유합니다. 전체 키는 동시에 8개의 요청을 허용하지만, 체험 키는 2개만 허용합니다. 사용자가 떠난 후에도 서버가 사용자의 스트림을 계속 읽고 있다면 해당 슬롯이 사용 중 상태가 됩니다. 클라이언트가 연결을 끊으면 요청을 취소하세요. Python에서는 stream.close()를 호출하고, Node에서는 stream.controller.abort()를 호출합니다.
브라우저로 스트림 중계
브라우저 코드에 API 키를 넣지 마세요. 일반적인 설정은 귀하의 서버에서 API를 stream: true로 호출하고 각 조각을 페이지로 전달하는 작은 엔드포인트입니다. Express를 사용한 Node 환경에서는 Content-Type: text/event-stream를 설정하고, 각 조각을 빈 줄과 함께 data: ...로 작성한 후 요청의 close 이벤트를 수신하여 원본 API 호출을 중단합니다. 페이지에서는 EventSource가 GET 엔드포인트를 처리하고, fetch과 리더를 사용하면 POST 본문을 처리할 수 있으며, 이는 메시지 역사를 보낼 때 필요한 방식입니다.
메시지 역사는 서버나 요청 본문에 보관하고, 대화가 길어지면 가장 오래된 턴을 잘라내세요. 컨텍스트 창은 프롬프트와 응답의 합계가 100,000 토큰이며, 이는 많은 채팅을 처리할 수 있지만 장기 세션이라면 결국 이 한도에 도달하게 됩니다.
스트리밍 중 속도 제한
제한은 일반 키의 경우 분당 300개 요청 및 동시 8개 요청이며, 체험 키의 경우 분당 60개 및 동시 2개입니다. 초과 시 HTTP 429가 반환됩니다. 오류 코드는 어떤 제한에 도달했는지 알려줍니다: rate_limited은 분당 요청이 너무 많음을 의미하고, concurrency은 동시에 너무 많음을 의미합니다. 일시적 과부하 시 API는 Retry-After: 5 헤더와 함께 429도 반환합니다.
429는 토큰이 스트리밍되기 전에 도착하므로 읽기 전에 처리하세요. 작은 재시도 래퍼면 충분합니다:
import time
from openai import OpenAI, RateLimitError
client = OpenAI(base_url="https://api.uncensoredllmapi.com/v1", api_key="YOUR_KEY")
def open_stream(messages, tries=4):
for n in range(tries):
try:
return client.chat.completions.create(
model="uncensored", messages=messages, stream=True
)
except RateLimitError as e:
wait = 5 if n == 0 else 5 * (n + 1)
time.sleep(wait)
raise RuntimeError("still rate limited")
많은 사용자를 위한 채팅 앱의 경우 concurrency 오류에 대한 실제 해결책은 동시에 최대 8개의 활성 스트림만 허용하는 측의 작은 큐입니다.
스트리밍 채팅 출시 전 체크리스트
- 마지막 청크에서 빈
choices를 방지하세요. - 부분 텍스트를 버퍼링하고 오류 시 저장하세요.
- 브라우저가 연결을 끊으면 업스트림 요청을 중단하세요.
- 활성 스트림을 동시성 제한으로 제한하세요.
- 스트림별 사용량 및 요청 ID를 로깅하세요.
- 서버 앞의 모든 역방향 프록시에서 응답 버퍼링을 비활성화하세요. 그렇지 않으면 토큰이 버스트로 도착합니다.
마지막 항목은 많은 첫 배포에서 실수를 유발합니다. 예를 들어 Nginx는 기본적으로 프록시된 응답을 버퍼링하므로 스트림은 로컬호스트에서는 작동하지만 버퍼링이 해당 경로에 대해 비활성화될 때까지 프로덕션에서 멈춘 것처럼 보입니다. 자유 텍스트 대신 JSON 출력을 보려면 JSON 모드에 대한 설명을 참조하세요. 위의 코드를 시도하려면 API 키를 생성하세요. 새 계정은 7일 동안 유효한 한 번의 클릭으로 $0.50의 체험 크레딧을 청구할 수 있습니다. 충전은 암호화폐(USDT on TRC20 또는 USDC on Base) 전용이며, $20부터 시작됩니다.
