Mistral AI 프로바이더

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

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

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

커스터마이즈가 필요하다면 @ai-sdk/mistral에서 createMistral을 불러와 원하는 설정으로 프로바이더 인스턴스를 만들 수 있어요:

import { createMistral } from '@ai-sdk/mistral';

const mistral = createMistral({
  // custom settings
});

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

• baseURL string

  API 호출에 다른 URL 접두사를 사용해요. 예를 들어 프록시 서버를 쓸 때 유용해요. 기본 접두사는 https://api.mistral.ai/v1이에요.

• apiKey string

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

• headers Record<string,string>

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

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

  커스텀 fetch 구현이에요. 기본값은 전역 fetch 함수예요. 요청을 가로채는 미들웨어로 쓸 수도 있고, 예를 들어 테스트용으로 커스텀 fetch 구현을 제공할 수도 있어요.

언어 모델 (Language Models)

프로바이더 인스턴스로 Mistral 채팅 API를 호출하는 모델을 만들 수 있어요. 첫 번째 인자는 모델 id예요. 예: mistral-large-latest. 일부 Mistral 채팅 모델은 툴 호출을 지원해요.

const model = mistral('mistral-large-latest');

Mistral 채팅 모델은 표준 호출 설정에 속하지 않는 추가 모델 설정도 지원해요. 옵션 인자로 전달하고 MistralLanguageModelChatOptions로 타입을 지정할 수 있어요:

import { mistral, type MistralLanguageModelChatOptions } from '@ai-sdk/mistral';
const model = mistral('mistral-large-latest');

await generateText({
  model,
  providerOptions: {
    mistral: {
      safePrompt: true, // optional safety prompt injection
      parallelToolCalls: false, // disable parallel tool calls (one tool per response)
    } satisfies MistralLanguageModelChatOptions,
  },
});

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

• safePrompt boolean

  모든 대화 전에 안전 프롬프트를 주입할지 여부예요.

  기본값은 false.

• documentImageLimit number

  문서에서 처리할 최대 이미지 수예요.

• documentPageLimit number

  문서에서 처리할 최대 페이지 수예요.

• strictJsonSchema boolean

  구조화된 출력에 엄격한 JSON 스키마 검증을 사용할지 여부예요. 스키마가 제공될 때만 적용되며 strict 플래그를 설정하고, 스키마가 제공되면 기본으로 사용되는 Custom Structured Outputs를 사용하는 것에 더해 적용돼요.

  기본값은 false.

• structuredOutputs boolean

  구조화된 출력을 사용할지 여부예요. 활성화하면 툴 호출과 객체 생성이 엄격해지고 제공된 스키마를 따르게 돼요.

  기본값은 true.

• parallelToolCalls boolean

  툴 사용 중 병렬 함수 호출을 활성화할지 여부예요. false로 설정하면 모델이 응답당 최대 하나의 툴을 사용해요.

  기본값은 true.

• promptCacheKey string

  프롬프트 접두사를 공유하는 요청의 캐시 친화력을 개선하는 안정적인 식별자예요.

프롬프트 캐시 친화력 (Prompt Cache Affinity)

Mistral 프롬프트 캐싱은 공유 프롬프트 접두사를 재사용해요. promptCacheKey를 안정적인 워크플로, 세션 또는 대화 식별자로 설정해 캐시 친화력을 개선하세요. 프로바이더는 이를 Mistral의 prompt_cache_key 요청 필드로 보내요:

import { mistral, type MistralLanguageModelChatOptions } from '@ai-sdk/mistral';
import { generateText } from 'ai';

const result = await generateText({
  model: mistral('mistral-medium-3.5'),
  system: 'Classify each support request as account, billing, or technical.',
  prompt: 'The dashboard shows an error when I open an invoice.',
  providerOptions: {
    mistral: {
      promptCacheKey: 'support-classification-workflow-v1',
    } satisfies MistralLanguageModelChatOptions,
  },
});

console.log(result.usage.inputTokenDetails.cacheReadTokens);

같은 안정적인 접두사가 있는 요청에는 같은 키를 사용하세요. 다단계 generateText와 streamText 호출은 모든 스텝에서 프로바이더 옵션을 재사용하므로, 단일 키가 전체 툴 루프에 적용돼요. 프롬프트 캐시 친화력은 최선 노력(best-effort)이며 캐시 히트를 보장하지 않아요.

캐시 키는 불투명한 식별자로 취급하세요. API 키, 비밀번호, 이메일 주소 또는 기타 민감한 개인 데이터를 포함하지 마세요.

문서 OCR (Document OCR)

Mistral 채팅 모델은 PDF 파일에 대한 문서 OCR을 지원해요. 프로바이더 옵션으로 이미지 및 페이지 한도를 선택적으로 설정할 수 있어요.

import { mistral, type MistralLanguageModelChatOptions } from '@ai-sdk/mistral';
import { generateText } from 'ai';

const result = await generateText({
  model: mistral('mistral-small-latest'),
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: 'What is an embedding model according to this document?',
        },
        {
          type: 'file',
          data: new URL(
            'https://github.com/vercel/ai/blob/main/examples/ai-functions/data/ai.pdf?raw=true',
          ),
          mediaType: 'application/pdf',
        },
      ],
    },
  ],
  // optional settings:
  providerOptions: {
    mistral: {
      documentImageLimit: 8,
      documentPageLimit: 64,
    } satisfies MistralLanguageModelChatOptions,
  },
});

추론 모델 (Reasoning Models)

Mistral은 단계별 사고 능력을 제공하는 추론 모델을 제공해요:

• magistral-small-latest: 효율적인 단계별 사고를 위한 소형 추론 모델
• magistral-medium-latest: 성능과 비용을 균형 있게 조정하는 더 강력한 추론 모델

이 모델들은 AI SDK가 자동으로 추출하는 구조화된 추론 콘텐츠를 반환해요. 추론은 결과의 reasoningText 속성으로 사용할 수 있어요:

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

const result = await generateText({
  model: mistral('magistral-small-latest'),
  prompt: 'What is 15 * 24?',
});

console.log('REASONING:', result.reasoningText);
// Output: "Let me calculate this step by step..."

console.log('ANSWER:', result.text);
// Output: "360"

SDK는 Mistral의 네이티브 추론 형식을 자동으로 파싱하고 결과에 별도의 reasoningText와 text 속성을 제공해요. 미들웨어가 필요하지 않아요.

구성 가능한 추론 (Configurable Reasoning)

일부 Mistral 모델은 reasoning 파라미터로 제어할 수 있는 구성 가능한 추론을 지원해요. AI SDK의 최상위 reasoning 설정을 사용해 reasoning effort를 제어할 수 있어요:

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

const result = await generateText({
  model: mistral('mistral-small-latest'),
  reasoning: 'high',
  prompt: 'What is 15 * 24?',
});

console.log('REASONING:', result.reasoningText);
console.log('ANSWER:', result.text);

현재 Mistral은 노력 수준으로 'high'와 'none'만 지원해요.

예시 (Example)

generateText 함수로 Mistral 언어 모델을 사용해 텍스트를 생성할 수 있어요:

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

const { text } = await generateText({
  model: mistral('mistral-large-latest'),
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});

Mistral 언어 모델은 streamText 함수에서도 사용할 수 있고 Output으로 구조화된 데이터 생성을 지원해요 (AI SDK Core 참고).

구조화된 출력 (Structured Outputs)

Mistral 채팅 모델은 JSON Schema를 사용한 구조화된 출력을 지원해요. Zod, Valibot 또는 원시 JSON Schema와 함께 generateText 또는 streamText를 Output과 사용할 수 있어요. SDK는 스키마를 Mistral의 response_format: { type: 'json_schema' }를 통해 보내요.

import { mistral } from '@ai-sdk/mistral';
import { generateText, Output } from 'ai';
import { z } from 'zod';

const result = await generateText({
  model: mistral('mistral-large-latest'),
  output: Output.object({
    schema: z.object({
      recipe: z.object({
        name: z.string(),
        ingredients: z.array(z.string()),
        instructions: z.array(z.string()),
      }),
    }),
  }),
  prompt: 'Generate a simple pasta recipe.',
});

console.log(JSON.stringify(result.output, null, 2));

프로바이더 옵션으로 엄격한 JSON Schema 검증을 활성화할 수 있어요:

import { mistral, type MistralLanguageModelChatOptions } from '@ai-sdk/mistral';
import { generateText, Output } from 'ai';
import { z } from 'zod';

const result = await generateText({
  model: mistral('mistral-large-latest'),
  providerOptions: {
    mistral: {
      strictJsonSchema: true,
    } satisfies MistralLanguageModelChatOptions,
  },
  output: Output.object({
    schema: z.object({
      title: z.string(),
      items: z.array(
        z.object({ id: z.string(), qty: z.number().int().min(1) }),
      ),
    }),
  }),
  prompt: 'Generate a small shopping list.',
});

모델 기능 (Model Capabilities)

음성 인식 모델 (Transcription Models)

.transcription() 팩토리 메서드로 Mistral 오디오 전사 API를 호출하는 모델을 만들 수 있어요:

const model = mistral.transcription('voxtral-mini-latest');

transcribe와 함께 Mistral 음성 인식 모델을 사용하세요:

import { mistral } from '@ai-sdk/mistral';
import { transcribe } from 'ai';
import { readFile } from 'node:fs/promises';

const result = await transcribe({
  model: mistral.transcription('voxtral-mini-latest'),
  audio: await readFile('audio.mp3'),
});

Mistral 음성 인식 모델은 추가 프로바이더 옵션을 지원해요. providerOptions.mistral로 전달하고 MistralTranscriptionModelOptions로 타입을 확인하세요:

import {
  mistral,
  type MistralTranscriptionModelOptions,
} from '@ai-sdk/mistral';
import { transcribe } from 'ai';
import { readFile } from 'node:fs/promises';

const result = await transcribe({
  model: mistral.transcription('voxtral-mini-latest'),
  audio: await readFile('audio.mp3'),
  providerOptions: {
    mistral: {
      timestampGranularities: ['segment'],
      diarize: true,
      contextBias: ['Vercel', 'AI_SDK'],
    } satisfies MistralTranscriptionModelOptions,
  },
});

다음 선택적 프로바이더 옵션을 사용할 수 있어요:

• language string

  오디오의 언어예요. en 같은 값. 제공하면 정확도가 향상될 수 있어요.

• temperature number

  전사를 위한 샘플링 온도예요.

• timestampGranularities Array<'segment' | 'word'>

  응답에 포함할 타임스탬프 세밀도예요. Mistral은 이 옵션을 language와 결합하는 것을 지원하지 않아요. 둘 다 제공하면 SDK가 InvalidArgumentError를 던져요.

• diarize boolean

  전사에서 화자를 식별할지 여부예요.

• contextBias string[]

  이름, 기술 용어 또는 도메인별 어휘의 철자를 안내하는 최대 100개의 단어나 구절이에요. 항목에 쉼표나 공백을 포함할 수 없으며, 여러 단어 구절에는 밑줄을 사용하세요.

정규화된 결과에는 Mistral이 반환할 때 트랜스크립트 텍스트, 언어, 시간 설정 세그먼트, 지속 시간이 포함돼요. Mistral 토큰 및 프롬프트-오디오 사용량은 result.providerMetadata.mistral.usage에서 사용할 수 있어요. 화자 분리(diarization)의 세그먼트 점수와 화자 ID는 result.providerMetadata.mistral.segments에서 사용할 수 있어요.

모델 기능 (Model Capabilities)

음성 모델 (Speech Models)

.speech() 팩토리 메서드로 Mistral 음성 API를 호출하는 모델을 만들 수 있어요:

const model = mistral.speech('voxtral-mini-tts-2603');

generateSpeech로 사전 설정 또는 저장된 음성 ID를 사용하세요:

import { mistral } from '@ai-sdk/mistral';
import { generateSpeech } from 'ai';

const result = await generateSpeech({
  model: mistral.speech('voxtral-mini-tts-2603'),
  text: 'Hello from the AI SDK!',
  voice: 'en_paul_neutral',
  outputFormat: 'mp3',
});

const audio = result.audio.uint8Array;

Mistral 음성 모델은 voice를 Mistral의 voice_id에 매핑해요. mp3, wav, pcm, flac, opus 출력 형식을 지원하고 기본값은 mp3예요. instructions, speed, language 설정은 지원되지 않으며 제공되면 경고를 발생시켜요.

Mistral은 base64 인코딩 참조 오디오로 일회용 음성 복제도 지원해요. providerOptions.mistral.refAudio로 전달하고 MistralSpeechModelOptions로 타입을 확인하세요:

import { readFile } from 'node:fs/promises';
import { mistral, type MistralSpeechModelOptions } from '@ai-sdk/mistral';
import { generateSpeech } from 'ai';

const referenceAudio = await readFile('./reference.mp3');

const result = await generateSpeech({
  model: mistral.speech('voxtral-mini-tts-2603'),
  text: 'Hello from the AI SDK!',
  providerOptions: {
    mistral: {
      refAudio: referenceAudio.toString('base64'),
    } satisfies MistralSpeechModelOptions,
  },
});

refAudio가 제공되면 voice보다 우선해요. 참조 오디오는 요청 메타데이터와 프로바이더가 반환한 API 호출 오류에서 마스킹돼요.

모델 기능 (Model Capabilities)

임베딩 모델 (Embedding Models)

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

const model = mistral.embedding('mistral-embed');

embed 함수로 Mistral 임베딩 모델을 사용해 임베딩을 생성할 수 있어요:

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

const { embedding } = await embed({
  model: mistral.embedding('codestral-embed-2505'),
  value: 'function add(a: number, b: number) { return a + b; }',
});

Mistral 임베딩 모델은 providerOptions.mistral을 통한 추가 프로바이더 옵션을 지원해요. MistralEmbeddingModelOptions로 검증할 수 있어요:

import { mistral, type MistralEmbeddingModelOptions } from '@ai-sdk/mistral';
import { embed } from 'ai';

const { embedding } = await embed({
  model: mistral.embedding('mistral-embed'),
  value: 'sunny day at the beach',
  providerOptions: {
    mistral: {
      metadata: { source: 'knowledge-base' },
      outputDimension: 1024,
      outputDtype: 'float',
    } satisfies MistralEmbeddingModelOptions,
  },
});

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

• metadata Record<string, unknown>

  임베딩 요청에 첨부할 추가 메타데이터예요.

• outputDimension number

  모델이 지원할 때 출력 임베딩의 차원이에요.

• outputDtype string

  모델이 지원할 때 출력 임베딩의 데이터 타입이에요. 'float', 'int8', 'uint8', 'binary' 또는 'ubinary'를 받아요.

모델 기능 (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

전체 사이트맵