Perplexity 프로바이더

프로바이더 인스턴스 (Provider Instance)

@ai-sdk/perplexity에서 기본 프로바이더 인스턴스 perplexity를 불러올 수 있어요:

import { perplexity } from '@ai-sdk/perplexity';

커스텀 구성이 필요하다면 createPerplexity를 불러와 원하는 설정으로 프로바이더 인스턴스를 만들 수 있어요:

import { createPerplexity } from '@ai-sdk/perplexity';

const perplexity = createPerplexity({
  apiKey: process.env.PERPLEXITY_API_KEY ?? '',
});

Perplexity 프로바이더 인스턴스를 커스터마이즈할 때 사용할 수 있는 선택적 설정은 다음과 같아요:

• baseURL string

  API 호출에 다른 URL 접두사를 사용해요. 기본 접두사는 https://api.perplexity.ai예요.

• apiKey string

  Authorization 헤더로 보내는 API 키예요. 기본값은 PERPLEXITY_API_KEY 환경 변수예요.

• headers Record<string,string>

  요청에 포함할 커스텀 헤더예요.

• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

  커스텀 fetch 구현이에요.

언어 모델 (Language Models)

프로바이더 인스턴스로 Perplexity 모델을 만들 수 있어요:

import { perplexity } from '@ai-sdk/perplexity';
import { generateText } from 'ai';

const { text } = await generateText({
  model: perplexity('low'),
  prompt: 'What are the latest developments in quantum computing?',
});

Agent API는 fast, low, medium, high, xhigh 프리셋을 제공해요. perplexity/sonar 같은 Agent API 모델 ID를 직접 전달할 수도 있어요.

버전 5는 Agent API만 사용해요. 레거시 Sonar 모델 ID와 프로바이더 옵션은 매핑되지 않아요. 업그레이드 전에 v4 Sonar에서 v5 Agent API로 마이그레이션을 참고하세요.

출처 (Sources)

응답을 생성하는 데 사용된 웹사이트는 결과의 sources 속성에 포함돼요:

import { perplexity } from '@ai-sdk/perplexity';
import { generateText } from 'ai';

const { text, sources } = await generateText({
  model: perplexity('low'),
  prompt: 'What are the latest developments in quantum computing?',
});

console.log(sources);

에이전트 툴 (Agent Tools)

providerOptions.perplexity.tools를 통해 네이티브 Agent API 툴을 전달하세요:

import {
  perplexity,
  type PerplexityLanguageModelOptions,
} from '@ai-sdk/perplexity';
import { generateText } from 'ai';

const { text, sources } = await generateText({
  model: perplexity('low'),
  prompt: 'Summarize recent US federal AI policy from official sources.',
  providerOptions: {
    perplexity: {
      tools: [
        {
          type: 'web_search',
          filters: {
            search_domain_filter: [
              'whitehouse.gov',
              'congress.gov',
              'federalregister.gov',
            ],
            search_recency_filter: 'month',
          },
          max_results: 10,
          search_context_size: 'medium',
        },
      ],
    } satisfies PerplexityLanguageModelOptions,
  },
});

지원되는 네이티브 툴은 web_search, fetch_url, people_search, finance_search, sandbox, mcp, connector예요. Agent API 프리셋에는 활성 상태로 유지되는 사전 구성된 툴이 포함돼요. tools 옵션은 명시적 툴을 추가하거나 직접 모델 ID를 사용할 때 툴을 제공할 수 있어요.

검색 및 가져오기 결과는 AI SDK 출처로 노출돼요. finance, sandbox, MCP 결과를 포함한 다른 네이티브 툴 트레이스는 response.body와 원시 스트림 청크(include: { rawChunks: true })에서 사용할 수 있어요. AI SDK 클라이언트 툴 호출로는 노출되지 않아요. 데이터 보존이 0인 계정은 finance_search와 sandbox 같은 파일 지원 툴을 거부할 수 있어요.

AI SDK 함수 툴은 최상위 tools 옵션으로 전달할 수 있어요:

import { perplexity } from '@ai-sdk/perplexity';
import { generateText, tool } from 'ai';
import { z } from 'zod';

const result = await generateText({
  model: perplexity('low'),
  prompt: 'What is the weather in San Francisco?',
  tools: {
    weather: tool({
      description: 'Get the weather for a city',
      inputSchema: z.object({ city: z.string() }),
      execute: async ({ city }) => ({ city, temperature: 18 }),
    }),
  },
});

프로바이더 옵션 및 메타데이터 (Provider Options and Metadata)

Perplexity 프로바이더는 providerMetadata를 통해 응답에 추가 메타데이터를 포함해요. providerOptions를 통해 추가 구성 옵션을 사용할 수 있어요.

import {
  perplexity,
  type PerplexityLanguageModelOptions,
} from '@ai-sdk/perplexity';
import { generateText } from 'ai';

const result = await generateText({
  model: perplexity('low'),
  prompt: 'What are the latest developments in quantum computing?',
  providerOptions: {
    perplexity: {
      max_steps: 5,
      store: true,
      reasoning: { effort: 'low' },
    } satisfies PerplexityLanguageModelOptions,
  },
});

console.log(result.providerMetadata);
// Example output:
// {
//   perplexity: {
//     usage: { citationTokens: null, numSearchQueries: 1 },
//     images: null,
//     cost: { totalCost: 0.006, currency: 'USD', ... },
//     toolCalls: { search_web: { invocation: 1 } },
//   },
// }

프로바이더 옵션 (Provider Options)

다음 Agent API 옵션을 사용할 수 있어요:

• instructions string

  Agent API 실행을 위한 최상위 지시사항이에요.

• tools array

  네이티브 Agent API 툴과 그 구성이에요.

• models string[]

  Agent API 라우팅을 위한 폴백 모델 목록이에요.

• max_steps number

  최대 에이전틱 스텝 수예요.

• max_tool_calls number

  최대 네이티브 툴 호출 수예요. 0으로 설정하면 모든 프리셋 툴이 비활성화돼요.

• previous_response_id string

  이전 Agent API 응답에서 대화를 이어가요.

• store boolean

  응답을 나중에 검색할 수 있는지 여부예요. store: false로 설정하면 검색에서 숨겨지지만 영속성을 비활성화하지 않으며, 응답은 여전히 previous_response_id 연속 소스로 사용될 수 있어요. 유지 동작과 계정별 제로 데이터 보존 제한은 Perplexity의 대화 상태 문서를 참고하세요.

• language_preference string

  ISO 639-1 언어 코드로 선호 응답 언어예요.

• reasoning object

  추론 구성. effort는 'minimal', 'low', 'medium', 'high', 'xhigh'를 지원해요.

• skills array

  Agent API 스킬 구성이에요.

프로바이더 메타데이터 (Provider Metadata)

응답 메타데이터는 다음을 포함해요:

• usage: citationTokens (Agent API 응답의 경우 항상 null)와 검색 쿼리 수
• cost: Perplexity가 반환한 토큰, 툴, 총 비용
• toolCalls: 네이티브 툴별 그룹화된 호출 횟수
• images: 항상 null; Agent API는 Sonar 이미지 결과를 반환하지 않아요

구조화된 출력 (Structured Output)

Output.object와 Output.array는 Agent API JSON 스키마 응답 형식을 보내요. 스키마 없는 JSON 출력은 지원되지 않아요.

입력 이미지 (Input Images)

이미지 URL과 데이터 입력은 Agent API input_image 파트로 변환돼요. Agent API는 Sonar에 해당하는 PDF 입력 필드를 제공하지 않으므로 PDF 파일 파트는 지원되지 않아요.

v4 Sonar에서 v5 Agent API로 마이그레이션 (Migrating from v4 Sonar to v5 Agent API)

각 Sonar 모델 ID를 Agent API 프리셋 또는 직접 Agent API 모델 ID로 교체하세요. 이 프리셋은 제안된 시작점이지 동등한 별칭이 아니에요. 프리셋이 다른 모델과 툴을 선택할 수 있으므로 비용, 지연 시간, 출력이 변경될 수 있어요.

예를 들어:

// v4
perplexity('sonar-pro');

// v5
perplexity('low');

Sonar 검색 및 추론 옵션을 Agent API 위치로 옮기세요:

프리셋 툴은 개별적으로 제거할 수 없어요. 검색을 비활성화해야 할 때는 web_search 툴이 없는 직접 모델 ID를 사용하거나, max_tool_calls: 0을 설정해 모든 프리셋 툴 호출을 비활성화하세요.

Agent API에는 Sonar PDF 또는 비디오 입력, 이미지 또는 비디오 결과, search_language_filter, stream_mode에 대응하는 것이 없어요. 관련 질문에는 프롬프팅이나 구조화된 출력이 필요해요. 마이그레이션 중에 이 옵션들을 제거하세요.

언어 요청은 이제 /v1/agent를 사용해요. 커스텀 baseURL 프록시는 해당 경로를 라우팅해야 해요. 원시 응답과 스트림은 Agent API의 타입이 있는 출력과 SSE 이벤트 형식을 사용하며, Perplexity 프로바이더 메타데이터, 사용량, 비용, 출처 식별자가 달라질 수 있어요. 임베딩 API는 변경되지 않아요.

PDF 입력의 경우 Agent API로 보내기 전에 문서 텍스트를 추출하거나, PDF 입력을 지원하는 다른 프로바이더를 선택하세요. 이미지/비디오 검색이나 언어 필터 검색이 필요한 경우 해당 기능을 별도 서비스로 옮기세요. 원시 Sonar 스트림 이벤트 소비자는 타입이 있는 Agent 이벤트를 위해 재작업하세요. 전체 API 수준 비교는 Perplexity의 마이그레이션 가이드를 참고하세요.

임베딩 모델 (Embedding Models)

.embedding() 팩토리 메서드로 Perplexity 임베딩 API를 호출하는 모델을 만들 수 있어요.

import { perplexity } from '@ai-sdk/perplexity';
import { embed } from 'ai';

const { embedding } = await embed({
  model: perplexity.embedding('pplx-embed-v1-4b'),
  value: 'sunny day at the beach',
});

API가 비용 내역을 반환하면 providerMetadata.perplexity.cost로 노출돼요 (inputCost, totalCost, currency):

const { embedding, providerMetadata } = await embed({
  model: perplexity.embedding('pplx-embed-v1-4b'),
  value: 'sunny day at the beach',
});

console.log(providerMetadata?.perplexity?.cost);
// { inputCost: 0.0001, totalCost: 0.0001, currency: 'USD' }

프로바이더 옵션 (Provider Options)

providerOptions.perplexity 필드로 프로바이더별 옵션을 전달할 수 있어요:

const { embedding } = await embed({
  model: perplexity.embedding('pplx-embed-v1-4b'),
  value: 'sunny day at the beach',
  providerOptions: {
    perplexity: {
      // Matryoshka truncation of the output vector (128 up to the model size).
      dimensions: 512,
      // Quantized encoding format. Defaults to 'base64_int8'.
      encodingFormat: 'base64_int8',
    },
  },
});

임베딩 모델에 사용할 수 있는 선택적 프로바이더 옵션은 다음과 같아요:

• dimensions number

  결과 출력 임베딩이 가져야 하는 차원 수예요. 모델의 전체 크기까지 128부터 범위(0.6b 모델은 1024, 4b 모델은 2560).

• encodingFormat 'base64_int8' | 'base64_binary'

  API가 반환하는 양자화 인코딩 형식이에요. 기본값은 base64_int8.

임베딩 모델 기능 (Embedding Model Capabilities)

모델 기능 (Model Capabilities)

더 알아보기 (Learn more)

• AI Gateway
• xAI Grok
• OpenAI
• Azure OpenAI
• Anthropic
• Open Responses
• Claude Platform on AWS
• Amazon Bedrock
• Groq
• Fal
• AssemblyAI
• GMI Cloud
• TypeSafe
• DeepInfra
• Deepgram
• Black Forest Labs
• Gladia
• Google
• Hume
• Google Vertex AI
• Rev.ai
• Baseten
• Hugging Face
• QuiverAI
• Fish Audio
• Mistral AI
• Z.AI
• Together.ai
• Cohere
• Fireworks
• Voyage AI
• DeepSeek
• Moonshot AI
• Alibaba
• MiniMax
• Cerebras
• Replicate
• Prodia
• Perplexity
• Luma
• ByteDance
• Kling AI
• ElevenLabs
• Cartesia

전체 사이트맵