스트리밍 값

스트리밍 값 (Streaming Values)

AI SDK RSC로 서버에서 클라이언트로 값을 스트리밍하는 방법을 설명하는 문서예요. 무엇을 어떻게 스트리밍할지 세밀하게 제어할 수 있어요.

출처: 문서

본문

경고: AI SDK RSC는 현재 실험 단계(experimental)예요. 프로덕션에서는 AI SDK UI 사용을 권장해요. RSC에서 UI로 마이그레이션하는 방법은 마이그레이션 가이드를 참고하세요.

RSC API는 서버에서 클라이언트로 값을 스트리밍할 수 있게 해 주는 여러 유틸리티 함수를 제공해요. 무엇을 어떻게 스트리밍할지 더 세밀하게 제어해야 할 때 유용해요.

참고: 이 유틸리티들은 streamText 같은 AI SDK Core 함수와 결합해 서버에서 클라이언트로 LLM 생성을 쉽게 스트리밍할 수도 있어요.

RSC API가 제공하는 streamable 값을 만드는 두 가지 함수가 있어요:

createStreamableValue - 스트림을 어떻게 생성, 업데이트, 종료할지에 대한 완전한 제어와 함께 streamable(직렬화 가능한) 값을 만들어요.
createStreamableUI - 스트림을 어떻게 생성, 업데이트, 종료할지에 대한 완전한 제어와 함께 streamable React 컴포넌트를 만들어요.

`createStreamableValue`

RSC API는 createStreamableValue를 사용해 문자열, 숫자, 객체, 배열 같은 직렬화 가능한 JavaScript 값을 서버에서 클라이언트로 스트리밍할 수 있게 해 줘요.

이것은 다음을 스트리밍하고 싶을 때 유용해요:

언어 모델의 텍스트 생성 실시간 스트리밍.
멀티모달 모델의 이미지 및 오디오 생성 버퍼 값.
다단계 에이전트 실행의 진행 업데이트.

Streamable 값 생성 (Creating a Streamable Value)

@ai-sdk/rsc에서 createStreamableValue를 임포트해 streamable 값을 만들 수 있어요.

'use server';

import { createStreamableValue } from '@ai-sdk/rsc';

export const runThread = async () => {
  const streamableStatus = createStreamableValue('thread.init');

  setTimeout(() => {
    streamableStatus.update('thread.run.create');
    streamableStatus.update('thread.run.update');
    streamableStatus.update('thread.run.end');
    streamableStatus.done('thread.end');
  }, 1000);

  return {
    status: streamableStatus.value,
  };
};

Streamable 값 읽기 (Reading a Streamable Value)

클라이언트에서 readStreamableValue를 사용해 streamable 값을 읽을 수 있어요. 이 함수는 값이 업데이트될 때마다 streamable의 값을 내보내는 async iterator를 반환해요:

import { readStreamableValue } from '@ai-sdk/rsc';
import { runThread } from '@/actions';

export default function Page() {
  return (
    <button
      onClick={async () => {
        const { status } = await runThread();

        for await (const value of readStreamableValue(status)) {
          console.log(value);
        }
      }}
    >
      Ask
    </button>
  );
}

Next.js App Router와 createStreamableValue를 사용해 텍스트 생성을(streamText로) 스트리밍하는 방법은 이 예제에서 배워보세요.

`createStreamableUI`

createStreamableUI는 React 컴포넌트를 담는 스트림을 만들어요. AI SDK Core API와 달리 이 함수는 대규모 언어 모델을 호출하지 않아요. 대신 React 컴포넌트 스트리밍을 세밀하게 제어할 수 있는 프리미티브를 제공해요.

`createStreamableUI` 사용 (Using `createStreamableUI`)

Server Action과 함께 createStreamableUI 함수를 어떻게 사용하는지 살펴볼게요.

'use server';

import { createStreamableUI } from '@ai-sdk/rsc';

export async function getWeather() {
  const weatherUI = createStreamableUI();

  weatherUI.update(<div style={{ color: 'gray' }}>Loading...</div>);

  setTimeout(() => {
    weatherUI.done(<div>It&apos;s a sunny day!</div>);
  }, 1000);

  return weatherUI.value;
}

먼저 빈 상태로 streamable UI를 만들고 로딩 메시지로 업데이트해요. 1초 후 최종 값으로 실제 날씨 정보를 전달하며 스트림을 done으로 표시해요. .value 속성은 클라이언트로 보낼 수 있는 실제 UI를 담고 있어요.

Streamable UI 읽기 (Reading a Streamable UI)

클라이언트 측에서는 getWeather Server Action을 호출하고 반환된 UI를 다른 React 컴포넌트처럼 렌더링할 수 있어요.

'use client';

import { useState } from 'react';
import { readStreamableValue } from '@ai-sdk/rsc';
import { getWeather } from '@/actions';

export default function Page() {
  const [weather, setWeather] = useState<React.ReactNode | null>(null);

  return (
    <div>
      <button
        onClick={async () => {
          const weatherUI = await getWeather();
          setWeather(weatherUI);
        }}
      >
        What&apos;s the weather?
      </button>

      {weather}
    </div>
  );
}

버튼을 클릭하면 getWeather 함수가 호출되고, 반환된 UI가 weather 상태로 설정되어 페이지에 렌더링돼요. 사용자는 먼저 로딩 메시지를 보고 1초 후 실제 날씨 정보를 보게 돼요.

단일 요청에서 여러 스트림을 처리하는 방법은 Multiple Streamables 가이드에서 더 알아보세요.

더 복잡한 사용 사례의 상태를 다루는 방법은 AI/UI State에서 더 알아보세요.

스트리밍 값