`smoothStream()`
smoothStream()
smoothStream은 streamText의 transform 옵션용 TransformStream을 만들어 텍스트와 reasoning 스트리밍을 버퍼링하고 구성 가능한 지연으로 완전한 청크를 방출해 부드럽게 만드는 유틸리티 함수입니다. 텍스트와 reasoning 응답을 스트리밍할 때 더 자연스러운 읽기 경험을 제공합니다.
출처: 문서
본문
import { smoothStream, streamText } from 'ai';
const result = streamText({
model,
prompt,
experimental_transform: smoothStream({
delayInMs: 20, // optional: defaults to 10ms
chunking: 'line', // optional: defaults to 'word'
}),
});
Import
import { smoothStream } from "ai"
API Signature
Parameters (파라미터)
delayInMs:number | null(선택) — 각 청크를 출력하는 사이의 지연(밀리초)입니다. 기본값은 10ms입니다. 지연을 비활성화하려면null로 설정하세요. 문서가 숨겨져 있을 때(예: 브라우저 백그라운드 탭)는 지연이 건너뛰어지는데, 그렇지 않으면 타이머 제한(throttling)이 스트림을 멈추게 할 수 있기 때문입니다.chunking:"word" | "line" | RegExp | Intl.Segmenter | (buffer: string) => string | undefined | null(선택) — 텍스트와 reasoning 내용을 스트리밍용으로 어떻게 청킹할지 제어합니다. 단어 단위로 스트리밍하려면"word"(기본값), 줄 단위로 스트리밍하려면"line", 로케일 인식 단어 분리를 위해Intl.Segmenter(CJK 언어에 권장)를 사용하거나, 커스텀 청킹을 위해 빈 문자열과 일치하지 않는 커스텀 콜백 또는RegExp패턴을 제공하세요.
비라틴 언어에서 단어 청킹의 주의점
단어 기반 청킹은 공백으로 단어를 구분하지 않는 다음 언어에서는 잘 동작하지 않습니다.
- 중국어
- 일본어
- 한국어
- 베트남어
- 태국어
Intl.Segmenter 사용 (권장)
이러한 언어의 경우 올바른 로케일 인식 단어 분리를 위해 Intl.Segmenter를 사용하는 것을 권장합니다. 이는 CJK 및 기타 언어에 정확한 단어 경계를 제공하는 선호되는 접근 방식입니다.
import { smoothStream, streamText } from 'ai';
__PROVIDER_IMPORT__;
const segmenter = new Intl.Segmenter('ja', { granularity: 'word' });
const result = streamText({
model: __MODEL__,
prompt: 'Your prompt here',
experimental_transform: smoothStream({
chunking: segmenter,
}),
});
import { smoothStream, streamText } from 'ai';
__PROVIDER_IMPORT__;
const segmenter = new Intl.Segmenter('zh', { granularity: 'word' });
const result = streamText({
model: __MODEL__,
prompt: 'Your prompt here',
experimental_transform: smoothStream({
chunking: segmenter,
}),
});
RegExp 기반 청킹
정규식 기반 청킹을 사용하려면 chunking 옵션에 RegExp를 전달하세요. 전역(global) 및 고정(sticky) 표현식이 지원됩니다. 표현식은 빈 문자열과 일치하지 않아야 합니다.
// To split on underscores:
smoothStream({
chunking: /_+/,
});
// Also can do it like this, same behavior
smoothStream({
chunking: /[^_]*_/,
});
커스텀 콜백 청킹
청킹에 커스텀 콜백을 사용하려면 chunking 옵션에 함수를 전달하세요.
smoothStream({
chunking: text => {
const findString = 'some string';
const index = text.indexOf(findString);
if (index === -1) {
return null;
}
return text.slice(0, index) + findString;
},
});
Returns (반환값)
다음과 같은 TransformStream을 반환합니다.
- 들어오는 텍스트와 reasoning 청크를 버퍼링
- 청킹 패턴이 발견되면 내용을 방출
- 부드러운 출력을 위해 청크 사이에 구성 가능한 지연 추가
- 비텍스트/reasoning 청크(툴 호출, 스텝 완료 이벤트 등)는 즉시 통과