`streamText()`
streamText()
언어 모델의 텍스트 생성을 스트리밍합니다. streamText 함수는 챗봇이나 기타 실시간 애플리케이션 같은 대화형 사용 사례에 사용할 수 있습니다. 툴로 UI 컴포넌트를 생성할 수도 있습니다.
runtimeContext, toolsContext, 툴 context 및 민감한 컨텍스트 필터링에 대한 안내는 Runtime and Tool Context를 참고하세요. 실제 동작을 보려면 예제를 확인하세요.
출처: 문서
본문
import { streamText } from 'ai';
__PROVIDER_IMPORT__;
const { textStream } = streamText({
model: __MODEL__,
prompt: 'Invent a new holiday and describe its traditions.',
});
for await (const textPart of textStream) {
process.stdout.write(textPart);
}
Import
import { streamText } from "ai"
API Signature
Parameters (파라미터)
model:LanguageModel— 사용할 언어 모델입니다. 예:openai('gpt-6-astra')instructions:Instructions— 모델의 동작을 지정하는 지시문입니다.prompt:string | Array<SystemModelMessage | UserModelMessage | AssistantModelMessage | ToolModelMessage>— 텍스트를 생성할 입력 프롬프트입니다.messages:Array<SystemModelMessage | UserModelMessage | AssistantModelMessage | ToolModelMessage>— 대화를 나타내는 메시지 목록입니다.useChat훅의 UI 메시지를 자동으로 변환합니다.allowSystemInMessages:boolean(선택) —prompt또는messages필드에 시스템 메시지를 허용할지 여부입니다. 기본값은false입니다.instructions옵션의 시스템 메시지는 항상 허용됩니다. 사용자 제어 메시지에 대해 이를 활성화하면 프롬프트 인젝션 위험이 생길 수 있습니다.tools:ToolSet— 모델이 접근하고 호출할 수 있는 툴입니다. 모델이 툴 호출을 지원해야 합니다.toolChoice:"auto" | "none" | "required" | { "type": "tool", "toolName": string }(선택) — 툴 선택 설정입니다. 툴이 어떻게 선택·실행되는지 지정하며 기본값은 "auto"입니다. "none"은 툴 실행을 비활성화하고, "required"는 툴 실행을 요구합니다.{ "type": "tool", "toolName": string }은 특정 툴을 실행하도록 지정합니다.maxOutputTokens:number(선택) — 생성할 최대 토큰 수입니다.temperature:number(선택) — 온도 설정입니다. 값은 프로바이더로 전달됩니다. 범위는 프로바이더와 모델에 따라 다릅니다.temperature또는topP중 하나만 설정하는 것을 권장합니다.topP:number(선택) — 핵(nucleus) 샘플링입니다. 값은 프로바이더로 전달됩니다. 범위는 프로바이더와 모델에 따라 다릅니다.temperature또는topP중 하나만 설정하는 것을 권장합니다.topK:number(선택) — 각 후속 토큰에 대해 상위 K 옵션에서만 샘플링합니다. "긴 꼬리"의 낮은 확률 응답을 제거하는 데 사용됩니다. 고급 사용 사례에만 권장합니다. 보통 temperature만 사용하면 됩니다.presencePenalty:number(선택) — 존재 페널티 설정입니다. 모델이 프롬프트에 이미 있는 정보를 반복할 가능성에 영향을 줍니다. 값은 프로바이더로 전달됩니다. 범위는 프로바이더와 모델에 따라 다릅니다.frequencyPenalty:number(선택) — 빈도 페널티 설정입니다. 모델이 같은 단어나 구를 반복적으로 사용할 가능성에 영향을 줍니다. 값은 프로바이더로 전달됩니다. 범위는 프로바이더와 모델에 따라 다릅니다.stopSequences:string[](선택) — 텍스트 생성을 멈추는 시퀀스입니다. 모델이 이 시퀀스 중 하나를 생성하면 더 이상 텍스트를 생성하지 않습니다.seed:number(선택) — 무작위 샘플링에 사용할 시드(정수)입니다. 설정되고 모델이 지원하면 호출은 결정적 결과를 생성합니다.reasoning:'provider-default' | 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'(선택) — 응답을 생성하기 전에 모델이 수행할 추론량을 제어합니다. 생략하면 프로바이더의 기본 동작이 사용됩니다.'provider-default'는 명시적으로 프로바이더 기본값을 요청합니다. reasoning을 지원하지 않는 프로바이더는 경고를 발생시킵니다. reasoning 관련providerOptions도 설정되어 있으면 그것이 우선하며 이 파라미터는 무시됩니다. 프로바이더별 매핑에 대한 자세한 내용은 reasoning 가이드를 참고하세요.maxRetries:number(선택) — 최대 재시도 횟수입니다. 재시도를 비활성화하려면 0으로 설정하세요. 기본: 2.streamRetries:number(선택) — 응답 스트리밍이 시작된 후 받은 프로바이더 오류 이벤트에 대한 자동 재시도 최대 횟수입니다. 재시도는 현재 모델 스텝만 다시 실행하며 완료된 이전 스텝과 그 툴 결과를 보존합니다. 실패한 시도의 툴 관련 출력과 클라이언트 측 툴 작업은 폐기되지만, 이미 방출된 다른 출력은 철회할 수 없으며 복구된 스텝 결과, 구조화된 출력 파싱, 응답 메시지 및 후속 모델 스텝에서 제외됩니다. 최종 요청/응답 메타데이터는 복구된 시도에서 옵니다. 복구된 출력이 시작되기 전에 열린 텍스트와 reasoning 파트가 종료됩니다.onStepStart는 논리적 스텝에 한 번,onLanguageModelCallStart는 각 시도에,onLanguageModelCallEnd는 모델 호출 종료에 도달하는 시도에 실행됩니다. 프로바이더가 실행한 툴 작업은 취소할 수 없으며 반복될 수 있습니다. 자동 재시도를 비활성화하려면 0으로 설정하고,onError가 콜백 지시 재시도를 한 번 요청할 수 있게 하세요. 자동 재시도가 구성되면onError는 재시도가 소진된 후 최대 한 번의 추가 재시도를 요청할 수 있어 총 복구 호출을streamRetries + 1로 제한합니다. 모든 스트림 재시도 동작을 비활성화하려면 생략하세요. 기본: 0.abortSignal:AbortSignal(선택) — 호출을 취소하는 데 사용할 수 있는 선택적 abort 신호입니다.timeout:number | { totalMs?: number; stepMs?: number; firstChunkMs?: number; chunkMs?: number; toolMs?: number; tools?: { [toolName]Ms?: number } }(선택) — 밀리초 단위 타임아웃입니다. 숫자 또는totalMs,stepMs,firstChunkMs,chunkMs,toolMs,tools속성을 가진 객체로 지정할 수 있습니다.totalMs는 전체 호출의 총 타임아웃을 설정합니다.stepMs는 각 개별 스텝(LLM 호출)의 타임아웃을 설정합니다.firstChunkMs는 각 스텝에서 첫 콘텐츠 포함 출력까지의 타임아웃을 설정합니다(메타데이터, 스트림 시작, 빈 델타, raw 청크, 전송 활동은 충족하지 않음).chunkMs는 출력 시작 후 콘텐츠 포함 출력 청크 사이의 타임아웃을 설정합니다(비콘텐츠 청크는 리셋하지 않음).toolMs는 모든 툴 실행의 기본 타임아웃을 설정합니다.tools는{toolName}Ms패턴(예: weatherMs, slowApiMs)으로 툴별 타임아웃 오버라이드를 설정하며toolMs보다 우선합니다. 툴이 타임아웃보다 오래 걸리면 중단되고 툴 오류를 반환하여 모델이 응답하거나 재시도할 수 있게 합니다.abortSignal과 함께 사용할 수 있습니다.headers:Record<string, string | undefined>(선택) — 요청과 함께 보낼 추가 HTTP 헤더입니다. HTTP 기반 프로바이더에만 적용됩니다.telemetry:TelemetryOptions(선택) — 텔레메트리 구성입니다.experimental_transform:StreamTextTransform | Array<StreamTextTransform>(선택) — 선택적 스트림 변환입니다. 제공된 순서대로 적용됩니다.streamText가 올바르게 동작하려면 스트림 변환은 스트림 구조를 유지해야 합니다.includeRawChunks:boolean(선택) — deprecated 되었습니다.include.rawChunks를 사용하세요. 스트림에 프로바이더의 raw 청크를 포함할지 여부입니다. 활성화하면 "raw" 유형의 raw 청크를 받아 AI SDK가 아직 감싸지 않은 최첨단 프로바이더 기능에 접근할 수 있습니다. 기본값은false입니다.providerOptions:Record<string,JSONObject> | undefined(선택) — 프로바이더별 옵션입니다. 외부 키는 프로바이더 이름, 내부 값은 메타데이터입니다. 세부 사항은 프로바이더에 따라 다릅니다.activeTools:ActiveTools<TOOLS>(선택) — 결과에서 툴 호출 및 결과 유형을 바꾸지 않고 모델이 호출할 수 있는 툴을 제한합니다. 기본적으로 모든 툴이 활성화됩니다. 툴 이름은 툴 세트의 문자열 키로 제한됩니다.toolOrder:ToolOrder<TOOLS>(선택) — 툴이 프로바이더로 전송되는 순서를 제어합니다. 목록은 부분적일 수 있습니다.toolOrder에 나열되지 않은 툴은 나열된 툴 뒤에 알파벳순으로 정렬되어 전송됩니다.toolApproval:ToolApprovalConfiguration<TOOLS, RUNTIME_CONTEXT>(선택) — 이 호출의 승인 구성입니다.GenericToolApprovalFunction을 전달해 모든 툴 호출을 하나의 콜백(toolCall,tools,toolsContext,messages,runtimeContext)으로 처리하거나, 각 키가 상태('not-applicable','approved','denied','user-approval') 또는 객체 형식({ type: 'denied', reason: 'blocked by policy' }) 또는SingleToolApprovalFunction(툴 입력과toolCallId,messages,toolContext,runtimeContext옵션을 받음)인 툴별 객체를 전달하세요.'not-applicable'은 기본 실행 경로로 툴을 승인 메타데이터 없이 실행합니다. 명시적인 자동 승인 요청/응답 파트를 원하면'approved','denied'또는 그 객체 형식을 사용하세요. 이 설정은 툴의needsApproval기본값보다 우선합니다.experimental_toolCallers:Experimental_ToolCallers<TOOLS>(선택) — 각 툴을 호출할 수 있는 호출자 툴을 구성합니다. callee 툴 이름을 키로 하고 호출 가능한 툴 이름 목록을 값으로 하는 객체를 전달하세요.@ai-sdk/code-mode의DIRECT_TOOL_CALL을 포함하면 구성된 툴을 모델이 직접 호출할 수 있습니다.experimental_refineToolInput:ToolInputRefinement<TOOLS>(선택) — 파싱된 툴 입력을 정제하는 함수로의 툴 이름 매핑입니다. 각 함수는 자기 툴의 타입이 지정된 입력을 받아 동일한 입력 타입 형태를 반환해야 합니다. 정제된 입력은 툴 실행, 스트림 파트, 라이프사이클 콜백, 텔레메트리에 사용됩니다.stopWhen:StopCondition<TOOLS> | Array<StopCondition<TOOLS>>(선택) — 마지막 스텝에 툴 결과가 있을 때 생성을 멈추는 조건입니다. 조건이 배열이면 그중 하나라도 충족되면 생성을 멈춥니다. 기본값:isStepCount(1).prepareStep:(options: PrepareStepOptions) => PrepareStepResult<TOOLS> | Promise<PrepareStepResult<TOOLS>>(선택) — 스텝에 다른 설정을 제공할 수 있는 선택적 함수입니다. 각 스텝의 모델, 모델 호출 설정, 툴 선택, 활성 툴, 지시문, 입력 메시지 및 실험적 샌드박스를 수정할 수 있습니다.runtimeContext:CONTEXT(선택) —prepareStep와 라이프사이클 콜백에 전달되는 사용자 정의 공유 런타임 컨텍스트 객체입니다.toolsContext:InferToolSetContext<TOOLS>— 툴 이름을 키로 하는 툴별 컨텍스트 맵입니다. 최소한 하나의 툴이contextSchema를 정의할 때 필요하며, 컨텍스트가 필요한 툴이 없으면 허용되지 않습니다.experimental_sandbox:Experimental_SandboxSession(선택) —prepareStep, 툴 설명 함수, 툴 실행에 전달되는 실험적 샌드박스 환경입니다. 툴은 설명 함수 옵션과 실행 옵션에서 접근할 수 있습니다.experimental_download:(requestedDownloads: Array<{ url: URL; isUrlSupportedByModel: boolean }>) => Promise<Array<null | { data: Uint8Array; mediaType?: string }>>(선택) — 프롬프트에 나타나는 URL을 가져오는 방식을 제어하는 커스텀 다운로드 함수입니다. 기본적으로 모델이 해당 미디어 타입의 URL을 지원하지 않으면 파일이 다운로드됩니다. 실험적 기능입니다. 모델이 지원할 때 URL을 직접 전달하려면null을 반환하고, 다운로드한 내용을 반환하려면 data와 media type을 반환하세요.include:{ requestBody?: boolean; requestMessages?: boolean; rawChunks?: boolean }(선택) — 스텝 결과에 요청 본문과 요청 메시지, 스트림에 raw 프로바이더 청크를 포함할지 제어합니다. 기본적으로 메모리 사용을 줄이기 위해 요청 본문, 요청 메시지, raw 청크는 제외됩니다.
Returns (반환값)
content:Promise<Array<ContentPart<TOOLS>>>— 모든 스텝에서 생성된 내용입니다. 스트림을 자동으로 소비합니다.finishReason:PromiseLike<'stop' | 'length' | 'content-filter' | 'tool-calls' | 'error' | 'other'>— 생성이 끝난 이유입니다. 스트림을 자동으로 소비합니다.rawFinishReason:PromiseLike<string | undefined>— 생성이 끝난 원시 이유입니다(프로바이더에서).usage:Promise<LanguageModelUsage>— 생성된 응답의 총 토큰 사용량입니다. 여러 스텝이 있으면 모든 스텝 사용량의 합입니다. 스트림을 자동으로 소비합니다.totalUsage:Promise<LanguageModelUsage>— deprecated 되었습니다.usage를 사용하세요.providerMetadata:Promise<ProviderMetadata | undefined>— deprecated 되었습니다.finalStep.providerMetadata를 사용하세요.text:Promise<string>— 생성된 전체 텍스트입니다. 스트림을 자동으로 소비합니다.reasoning:Promise<Array<ReasoningOutput | ReasoningFileOutput>>— deprecated 되었습니다.finalStep.reasoning을 사용하세요.
Types (타입)
ActiveTools
type ActiveTools<TOOLS extends ToolSet> =
| ReadonlyArray<keyof TOOLS & string>
| undefined;
생성 스텝을 나열된 툴 이름으로 제한합니다. undefined는 툴 제한이 적용되지 않음을 의미합니다.
Examples (예제)
- Next.js에서 언어 모델이 생성한 텍스트 스트리밍하기
- Next.js에서 언어 모델이 생성한 채팅 완성 스트리밍하기
- Node.js에서 언어 모델이 생성한 텍스트 스트리밍하기
- Node.js에서 언어 모델이 생성한 채팅 완성 스트리밍하기