Mistral AI Migration Deep Dive
Current State
!npm list openai @anthropic-ai/sdk @mistralai/mistralai 2>/dev/null | grep -E "openai|anthropic|mistral" || echo 'No AI SDKs found'
Overview
Comprehensive migration guide from OpenAI or Anthropic to Mistral AI using the adapter pattern with feature-flag controlled rollout. Covers model mapping, API differences, prompt adjustments, validation testing, and rollback procedures.
Prerequisites
- Current AI integration documented
- Mistral AI SDK installed (
@mistralai/mistralai)
- Feature flag infrastructure (env vars or LaunchDarkly)
- Rollback plan tested
Migration Complexity
| Migration | Effort | Duration | Risk |
|---|
| Fresh install (no existing AI) | Low | Days | Low |
| OpenAI to Mistral | Medium | 1-2 weeks | Medium |
| Anthropic to Mistral | Medium | 1-2 weeks | Medium |
| Multi-provider to Mistral | High | 2-4 weeks | Medium |
Instructions
Step 1: Assessment — Find All AI Touchpoints
set -euo pipefail
echo "=== AI Integration Assessment ==="
echo "OpenAI imports: $(grep -r "from 'openai'" src/ --include='*.ts' -l 2>/dev/null | wc -l)"
echo "Anthropic imports: $(grep -r "from '@anthropic'" src/ --include='*.ts' -l 2>/dev/null | wc -l)"
echo "Chat completions: $(grep -r "chat\.completions\|messages\.create" src/ --include='*.ts' -c 2>/dev/null | wc -l)"
echo "Embeddings: $(grep -r "embeddings\.create" src/ --include='*.ts' -c 2>/dev/null | wc -l)"
echo "Streaming: $(grep -r "stream\|for await" src/ --include='*.ts' -c 2>/dev/null | wc -l)"
Step 2: Model Mapping
| OpenAI | Anthropic | Mistral | Notes |
|---|
| gpt-4o | claude-3-5-sonnet | mistral-large-latest | Complex reasoning |
| gpt-4o-mini | claude-3-5-haiku | mistral-small-latest | Fast, cheap |
| gpt-3.5-turbo | — | mistral-small-latest | General purpose |
| text-embedding-3-small | — | mistral-embed | 1024 dims (vs 1536) |
| — | — | codestral-latest | Code-specialized |
| gpt-4-vision | claude-3-5-sonnet | pixtral-large-latest | Vision + text |
Step 3: Provider-Agnostic Adapter
export interface Message {
role: 'system' | 'user' | 'assistant' | 'tool';
content: string;
}
export interface ChatOptions {
model?: string;
temperature?: number;
maxTokens?: number;
stream?: boolean;
}
export interface ChatResponse {
content: string;
usage: { inputTokens: number; outputTokens: number };
model: string;
}
export interface AIAdapter {
chat(messages: Message[], options?: ChatOptions): Promise<ChatResponse>;
chatStream(messages: Message[], options?: ChatOptions): AsyncGenerator<string>;
embed(texts: []): <[][]>;
}
Step 4: Mistral Adapter
import { Mistral } from '@mistralai/mistralai';
import type { AIAdapter, Message, ChatOptions, ChatResponse } from './types.js';
export class MistralAdapter implements AIAdapter {
private client: Mistral;
private defaultModel: string;
constructor(apiKey: string, defaultModel = 'mistral-small-latest') {
this.client = new Mistral({ apiKey });
this.defaultModel = defaultModel;
}
async chat(messages: Message[], options?: ChatOptions): Promise<ChatResponse> {
const response = await this.client.chat.complete({
model: options?.model ?? this.,
messages,
: options?.,
: options?.,
});
{
: response.?.[]?.?. ?? ,
: {
: response.?. ?? ,
: response.?. ?? ,
},
: response. ?? .,
};
}
*(: [], ?: ): <> {
stream = ...({
: options?. ?? .,
messages,
: options?.,
: options?.,
});
( event stream) {
content = event.?.?.[]?.?.;
(content) content;
}
}
(: []): <[][]> {
response = ...({
: ,
: texts,
});
response..( d.);
}
}
Step 5: Feature-Flag Controlled Rollout
import { MistralAdapter } from './mistral.adapter.js';
import { OpenAIAdapter } from './openai.adapter.js';
export function createAdapter(): AIAdapter {
const rolloutPercent = parseInt(process.env.MISTRAL_ROLLOUT_PERCENT ?? '0');
const useMistral = Math.random() * 100 < rolloutPercent;
if (useMistral) {
console.log('[AI] Using Mistral');
return new MistralAdapter(process.env.MISTRAL_API_KEY!);
}
console.log('[AI] Using OpenAI (legacy)');
return new OpenAIAdapter(process.env.OPENAI_API_KEY!);
}
Step 6: Gradual Rollout Plan
| Phase | Rollout % | Duration | Criteria to Advance |
|---|
| 0. Validation | 0% | 1-2 days | A/B tests pass |
| 1. Canary | 5% | 2-3 days | Error rate < 1%, latency OK |
| 2. Partial | 25% | 3-5 days | Quality metrics match |
| 3. Majority | 50% | 5-7 days | Cost reduction confirmed |
| 4. Full | 100% | — | Remove old adapter code |
export MISTRAL_ROLLOUT_PERCENT=5
export MISTRAL_ROLLOUT_PERCENT=25
export MISTRAL_ROLLOUT_PERCENT=100
export MISTRAL_ROLLOUT_PERCENT=0
Step 7: A/B Validation Testing
async function validateMigration(adapter1: AIAdapter, adapter2: AIAdapter) {
const testPrompts = [
'Summarize: TypeScript adds static typing to JavaScript.',
'Classify: "The app crashes on login" — bug, feature, or question?',
'What is 2+2?',
];
for (const prompt of testPrompts) {
const messages = [{ role: 'user' as const, content: prompt }];
const [r1, r2] = await Promise.all([
adapter1.chat(messages, { temperature: 0 }),
adapter2.chat(messages, { temperature: 0 }),
]);
console.log(`Prompt: ${prompt.slice(0, 50)}...`);
console.log(` Provider 1: ${r1.content.slice(0, 100)} (${r1.usage.outputTokens} tokens)`);
console.log(` Provider 2: ${r2.content.slice(0, 100)} ( tokens)`);
.();
}
}
Key API Differences
| Feature | OpenAI | Mistral |
|---|
| SDK import | import OpenAI from 'openai' | import { Mistral } from '@mistralai/mistralai' |
| Chat method | client.chat.completions.create() | client.chat.complete() |
| Stream events | chunk.choices[0]?.delta?.content | event.data?.choices?.[0]?.delta?.content |
| Embeddings | client.embeddings.create() | client.embeddings.create() (same) |
| Tool calling | Identical JSON Schema format | Identical JSON Schema format |
| JSON mode | response_format: { type: 'json_object' } | responseFormat: { type: 'json_object' } |
| Vision | Base64 in content array | Same approach with pixtral models |
Error Handling
| Issue | Cause | Solution |
|---|
| Different output quality | Model differences | Adjust prompts, tune temperature |
| Embedding dimension mismatch | 1536 vs 1024 | Re-embed all vectors, update vector DB config |
| Missing feature | Not supported by Mistral | Implement fallback in adapter |
| Cost increase | Token counting differs | Monitor and optimize prompts |
Resources
Output
- Integration assessment with effort estimation
- Provider-agnostic adapter interface
- Mistral adapter implementation
- Feature-flag controlled gradual rollout
- Model mapping and API difference reference
- A/B validation test suite
- Rollback procedure (set MISTRAL_ROLLOUT_PERCENT=0)
