마이그레이션 가이드

마이그레이션 가이드 (Migration Guides)

이 가이드는 다른 제공자에서 Mistral API로 전환할 때 필요한 구체적인 코드 변경 사항을 다뤄요. Mistral Chat Completions API는 OpenAI와 동일한 요청 구조를 따르므로, 대부분의 마이그레이션은 클라이언트 import, base URL, 모델 이름을 바꾸는 것으로 끝나요. 아래에서 원본 플랫폼을 골라 정확한 단계와 동작하는 코드 예시를 확인하세요.

출처: 문서

본문

From OpenAIFrom self-hosted Llama

Mistral API는 OpenAI API와 동일한 Chat Completions 구조를 따라요. 대부분의 애플리케이션에서 마이그레이션은 세 가지를 바꾸면 됩니다: 클라이언트 import, 초기화 호출, 모델 이름.

OpenAI에서 마이그레이션 (Migrate from OpenAI)

클라이언트 업데이트

PythonTypeScript

변경 전 (OpenAI):

from openai import OpenAI

client = OpenAI(api_key="sk-...")
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)

변경 후 (Mistral):

from mistralai.client import Mistral

client = Mistral(api_key="your_mistral_api_key")
response = client.chat.complete(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Hello"}],
)

주요 차이점

	OpenAI	Mistral
Python client	openai.OpenAI	mistralai.Mistral
Chat method	client.chat.completions.create	client.chat.complete
Streaming method	client.chat.completions.create(stream=True)	client.chat.stream
Base URL	https://api.openai.com/v1	https://api.mistral.ai/v1

모델 이름 매핑

OpenAI model	Mistral equivalent
gpt-4o	mistral-large-latest
gpt-4o-mini	mistral-small-latest
text-embedding-3-small	mistral-embed

OpenAI 호환 base URL 사용하기

애플리케이션이 OpenAI 호환 클라이언트(LangChain, LlamaIndex, 기타 서드파티 라이브러리)를 사용한다면, base URL과 모델 이름만 바꿔서 Mistral API를 가리키면 돼요. 라이브러리를 바꿀 필요가 없어요.

from openai import OpenAI

client = OpenAI(
    api_key="your_mistral_api_key",
    base_url="https://api.mistral.ai/v1",
)

response = client.chat.completions.create(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Hello"}],
)

자체 호스팅 Llama에서 마이그레이션 (Migrate from self-hosted Llama)

토크나이저 (Tokenizer)

Mistral 모델은 Llama와 다른 토크나이저를 사용해요. 토큰 수를 직접 계산하거나 원시 토크나이제이션을 처리한다면 도구를 업데이트해야 해요.

공식 Mistral 토크나이저를 설치하세요:

pip install mistral-common

텍스트를 토크나이즈하는 데 사용해요:

from mistral_common.tokens.tokenizers.mistral import MistralTokenizer

tokenizer = MistralTokenizer.v3()
result = tokenizer.encode_chat_completion(
    messages=[{"role": "user", "content": "Hello, world!"}]
)
print(result.tokens)

Hugging Face의 Mistral 모델은 transformers 라이브러리와도 호환돼요. apply_chat_template를 사용하면 포맷을 자동으로 처리해요.

프롬프트 형식 (Prompt format)

경고: Mistral 모델은 Llama 2의 [INST] / [/INST] 프롬프트 형식을 사용하지 않아요. 원시 Llama 2 형식 문자열을 Mistral 모델에 전달하면 출력 품질이 떨어져요. 테스트 전에 프롬프트 템플릿을 업데이트하세요.

apply_chat_template를 사용해 프롬프트를 올바르게 포맷하세요:

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("mistralai/Mistral-7B-Instruct-v0.3")
messages = [{"role": "user", "content": "Hello"}]
formatted = tokenizer.apply_chat_template(messages, tokenize=False)

모델 선택

Self-hosted Llama model	Mistral equivalent
Llama 3 8B Instruct	Mistral 7B Instruct (open-weight)
Llama 3 70B Instruct	Mixtral 8x22B Instruct (open-weight)
Any self-hosted	API: mistral-large-latest (managed)

Mistral의 모든 오픈웨이트 모델은 Hugging Face에서 Mistral 라이선스로 제공돼요.

Python SDK v2로 마이그레이션 (Migrate to Python SDK v2)

Python SDK 2.0.0 버전은 소수의 호환성 파괴 변경(breaking changes)을 도입해요. 나머지 모든 API(chat, streaming, embeddings, agents, function calling, batch)는 변경이 없어요.

패키지 업데이트

SDK V1은 mistralai<2에, V2는 mistralai>=2에 해당해요. 실행:

pip install "mistralai>=2"

import 경로 업데이트

변경 전 (V1):

from mistralai.client import Mistral

변경 후 (V2):

from mistralai.client import Mistral

Azure AI (해당하는 경우)

변경 전 (V1):

# pip install mistralai-azure>=1.0.0
from mistralai_azure import MistralAzure

client = MistralAzure(
    azure_endpoint=os.environ["AZUREAI_ENDPOINT"],
    azure_api_key=os.environ["AZUREAI_API_KEY"],
)

변경 후 (V2):

# pip install mistralai>=2.0.0
from mistralai.azure.client import MistralAzure

client = MistralAzure(
    server_url=os.environ["AZUREAI_ENDPOINT"],
    api_key=os.environ["AZUREAI_API_KEY"],
)

Google Cloud / Vertex AI (해당하는 경우)

변경 전 (V1):

# pip install mistralai[gcp]
from mistralai_gcp import MistralGoogleCloud

client = MistralGoogleCloud(
    region=os.environ["GOOGLE_CLOUD_REGION"],
    project_id=os.environ["GOOGLE_CLOUD_PROJECT_ID"],
)

변경 후 (V2):

# pip install mistralai>=2.0.0  (no separate package needed)
from mistralai.gcp.client import MistralGCP

# Auth is handled automatically via google.auth.default()
# Region defaults to "europe-west4"; override if needed:
# client = MistralGCP(region="us-central1", project_id="my-project")
client = MistralGCP()

요약 (Summary)

Area	V1	V2
Package	mistralai<2	mistralai>=2
Core import	from mistralai import Mistral	from mistralai.client import Mistral
Azure import	from mistralai_azure import MistralAzure	from mistralai.azure.client import MistralAzure
Azure constructor	azure_endpoint= , azure_api_key=	server_url= , api_key=
GCP import	from mistralai_gcp import MistralGoogleCloud	from mistralai.gcp.client import MistralGCP
GCP auth	GOOGLE_CLOUD_REGION + GOOGLE_CLOUD_PROJECT_ID env vars	automatic via google.auth.default()
All other APIs	—	unchanged

마이그레이션 가이드