텍스트 완성

텍스트 완성 (Completion)

useCompletion 훅으로 애플리케이션에서 텍스트 완성을 처리하는 사용자 인터페이스를 만들 수 있습니다. AI 프로바이더에서 텍스트 완성을 스트리밍하고, 채팅 입력의 상태를 관리하며, 새 메시지가 수신되면 UI를 자동으로 갱신합니다.

useCompletion 훅은 이제 @ai-sdk/react 패키지의 일부입니다. 이 가이드에서는 useCompletion 훅으로 텍스트 완성을 생성하고 실시간으로 사용자에게 스트리밍하는 방법을 배웁니다.

출처: 공식문서

본문

예시

app/page.tsx

'use client';

import { useCompletion } from '@ai-sdk/react';

export default function Page() {
  const { completion, input, handleInputChange, handleSubmit } = useCompletion({
    api: '/api/completion',
  });

  return (
    <form onSubmit={handleSubmit}>
      <input
        value={input}
        onChange={handleInputChange}
      />
      <button type="submit">Send</button>
      <div>{completion}</div>
    </form>
  );
}

app/api/completion/route.ts

import {
  createUIMessageStreamResponse,
  streamText,
  toUIMessageStream,
} from 'ai';

// Allow streaming responses up to 30 seconds
export const maxDuration = 30;

export async function POST(req: Request) {
  const { prompt }: { prompt: string } = await req.json();

  const result = streamText({
    model: "xai/grok-4.6",
    prompt,
  });

  return createUIMessageStreamResponse({
    stream: toUIMessageStream({ stream: result.stream }),
  });
}

Page 컴포넌트에서 useCompletion 훅은 사용자가 메시지를 제출할 때마다 AI 프로바이더 엔드포인트에 요청합니다. 완성은 실시간으로 스트리밍되어 UI에 표시됩니다.

커스터마이즈된 UI

useCompletion은 코드로 프롬프트를 관리하고, 로딩·오류 상태를 보여주고, 사용자 상호작용 없이 메시지를 갱신하는 방법도 제공합니다.

로딩과 오류 상태

챗봇이 사용자 메시지를 처리하는 동안 로딩 스피너를 보여주려면 useCompletion 훅이 반환하는 isLoading 상태를 사용합니다:

const { isLoading, ... } = useCompletion();

return (
  <>
    {isLoading ? <Spinner /> : null}
  </>
);

취소

AI 프로바이더에서 응답 메시지가 스트리밍되는 동안 중단하는 것도 흔한 사용 사례입니다. useCompletion 훅이 반환하는 stop 함수를 호출하면 됩니다.

UI 업데이트 스로틀링

이 기능은 현재 React에서만 사용할 수 있습니다. 기본적으로 useCompletion 훅은 새 청크가 수신될 때마다 렌더를 트리거합니다. throttle 옵션으로 UI 업데이트를 스로틀링할 수 있습니다.

이벤트 콜백

useCompletion은 챗봇 라이프사이클의 여러 단계를 처리하는 선택적 이벤트 콜백도 제공합니다. 로깅, 분석, 커스텀 UI 업데이트 같은 추가 작업을 트리거하는 데 사용할 수 있습니다.

const { ... } = useCompletion({
  onFinish: (prompt: string, completion: string) => {
    console.log('Finished streaming completion:', completion);
  },
  onError: (error: Error) => {
    console.error('An error occurred:', error);
  },
});

요청 옵션 구성

기본적으로 useCompletion 훅은 프롬프트를 요청 본문의 일부로 하여 /api/completion 엔드포인트에 HTTP POST 요청을 보냅니다. useCompletion 훅에 추가 옵션을 전달해 요청을 커스터마이즈할 수 있습니다:

const { messages, input, handleInputChange, handleSubmit } = useCompletion({
  api: '/api/custom-completion',
  headers: {
    Authorization: 'your_token',
  },
  body: {
    user_id: '123',
  },
  credentials: 'same-origin',
});

이 예시에서 useCompletion 훅은 지정된 헤더, 추가 본문 필드, 자격증명으로 /api/completion 엔드포인트에 POST 요청을 보냅니다. 서버측에서 이 추가 정보로 요청을 처리할 수 있습니다.

추가 본문 필드에 타입을 제공할 수 있습니다. 이 타입은 훅에 구성된 본문과 complete에 전달된 본문 모두에 적용됩니다:

type CompletionBody = {
  model: 'fast' | 'smart';
};

const { complete } = useCompletion<CompletionBody>({
  body: {
    model: 'fast',
  },
});

await complete('What is a completion?', {
  body: {
    model: 'smart',
  },
});

텍스트 완성