mistral_translator 0.1.0 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +21 -0
- data/README.md +189 -121
- data/README_TESTING.md +33 -0
- data/SECURITY.md +157 -0
- data/docs/.nojekyll +2 -0
- data/docs/404.html +30 -0
- data/docs/README.md +153 -0
- data/docs/advanced-usage/batch-processing.md +158 -0
- data/docs/advanced-usage/error-handling.md +106 -0
- data/docs/advanced-usage/monitoring.md +133 -0
- data/docs/advanced-usage/summarization.md +86 -0
- data/docs/advanced-usage/translations.md +141 -0
- data/docs/api-reference/callbacks.md +231 -0
- data/docs/api-reference/configuration.md +74 -0
- data/docs/api-reference/errors.md +673 -0
- data/docs/api-reference/methods.md +539 -0
- data/docs/getting-started.md +179 -0
- data/docs/index.html +27 -0
- data/docs/installation.md +142 -0
- data/docs/migration-0.1.0-to-0.2.0.md +61 -0
- data/docs/rails-integration/adapters.md +84 -0
- data/docs/rails-integration/controllers.md +107 -0
- data/docs/rails-integration/jobs.md +97 -0
- data/docs/rails-integration/setup.md +339 -0
- data/examples/basic_usage.rb +129 -102
- data/examples/batch-job.rb +511 -0
- data/examples/monitoring-setup.rb +499 -0
- data/examples/rails-model.rb +399 -0
- data/lib/mistral_translator/adapters.rb +261 -0
- data/lib/mistral_translator/client.rb +103 -100
- data/lib/mistral_translator/client_helpers.rb +161 -0
- data/lib/mistral_translator/configuration.rb +171 -1
- data/lib/mistral_translator/errors.rb +16 -0
- data/lib/mistral_translator/helpers.rb +292 -0
- data/lib/mistral_translator/helpers_extensions.rb +150 -0
- data/lib/mistral_translator/levenshtein_helpers.rb +40 -0
- data/lib/mistral_translator/logger.rb +28 -4
- data/lib/mistral_translator/prompt_builder.rb +93 -41
- data/lib/mistral_translator/prompt_helpers.rb +83 -0
- data/lib/mistral_translator/prompt_metadata_helpers.rb +42 -0
- data/lib/mistral_translator/response_parser.rb +194 -23
- data/lib/mistral_translator/security.rb +72 -0
- data/lib/mistral_translator/summarizer.rb +41 -2
- data/lib/mistral_translator/translator.rb +174 -98
- data/lib/mistral_translator/translator_helpers.rb +268 -0
- data/lib/mistral_translator/version.rb +1 -1
- data/lib/mistral_translator.rb +51 -25
- metadata +39 -3
data/docs/README.md
ADDED
@@ -0,0 +1,153 @@
|
|
1
|
+
> **Navigation :** [🏠 Home](README.md) • [📖 API Reference](api-reference/methods.md) • [⚡ Advanced Usage](advanced-usage/translations.md) • [🛤️ Rails Integration](rails-integration/setup.md)
|
2
|
+
|
3
|
+
---
|
4
|
+
|
5
|
+
# Documentation MistralTranslator
|
6
|
+
|
7
|
+
Bienvenue dans la documentation complète de **MistralTranslator**, une gem Ruby puissante pour la traduction et la synthèse de texte utilisant l'API Mistral AI.
|
8
|
+
|
9
|
+
## 🚀 Démarrage Rapide
|
10
|
+
|
11
|
+
```ruby
|
12
|
+
# Installation
|
13
|
+
gem 'mistral_translator'
|
14
|
+
|
15
|
+
# Configuration
|
16
|
+
MistralTranslator.configure { |c| c.api_key = ENV['MISTRAL_API_KEY'] }
|
17
|
+
|
18
|
+
# Usage
|
19
|
+
result = MistralTranslator.translate("Bonjour le monde", from: "fr", to: "en")
|
20
|
+
# => "Hello world"
|
21
|
+
```
|
22
|
+
|
23
|
+
## 📚 Guide de Documentation
|
24
|
+
|
25
|
+
### 🎯 Pour Commencer
|
26
|
+
|
27
|
+
| Fichier | Description | Niveau |
|
28
|
+
| ------------------------------------------------------ | ----------------------------------------------- | -------- |
|
29
|
+
| [Installation](installation.md) | Installation de la gem et configuration de base | Débutant |
|
30
|
+
| [Guide de Démarrage](getting-started.md) | Premiers pas avec exemples simples | Débutant |
|
31
|
+
| [Exemples de Base](../examples/basic_usage.rb) | Code commenté pour débuter | Débutant |
|
32
|
+
| [Migration 0.1.0 → 0.2.0](migration-0.1.0-to-0.2.0.md) | Changements clés et guide de migration | Tous |
|
33
|
+
|
34
|
+
### ⚡ Fonctionnalités Avancées
|
35
|
+
|
36
|
+
| Fichier | Description | Contenu Principal |
|
37
|
+
| -------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------- |
|
38
|
+
| [Traductions Avancées](advanced-usage/translations.md) | Contexte, glossaires, HTML, auto-détection | `translate_with_confidence()`, `translate_auto()` |
|
39
|
+
| [Traitement par Lot](advanced-usage/batch-processing.md) | Optimisation batch, multi-langues, progression | `translate_batch()`, `translate_to_multiple()` |
|
40
|
+
| [Résumés Intelligents](advanced-usage/summarization.md) | Multi-niveaux, multi-langues, Rails | `summarize()`, `summarize_tiered()` |
|
41
|
+
| [Gestion des Erreurs](advanced-usage/error-handling.md) | Retry, circuit breaker, fallback strategies | Patterns de robustesse |
|
42
|
+
| [Monitoring](advanced-usage/monitoring.md) | Métriques, dashboard, alertes | Analytics et observabilité |
|
43
|
+
|
44
|
+
### 🛤️ Intégration Rails
|
45
|
+
|
46
|
+
| Fichier | Description | Gems Supportées |
|
47
|
+
| ------------------------------------------------------- | --------------------------------------- | ------------------------- |
|
48
|
+
| [Configuration Rails](rails-integration/setup.md) | Initializers, environnements, callbacks | Rails 7+ |
|
49
|
+
| [Adaptateurs de Modèles](rails-integration/adapters.md) | Intégration transparente avec gems I18n | Mobility, Globalize, I18n |
|
50
|
+
| [Jobs Asynchrones](rails-integration/jobs.md) | Traduction en arrière-plan | Sidekiq, ActiveJob |
|
51
|
+
| [Controllers & API](rails-integration/controllers.md) | Endpoints, dashboard admin | REST API, Admin UI |
|
52
|
+
|
53
|
+
### 📖 Référence API
|
54
|
+
|
55
|
+
| Fichier | Description | Usage |
|
56
|
+
| ----------------------------------------------- | ----------------------------------- | ----------------------------- |
|
57
|
+
| [Configuration](api-reference/configuration.md) | Toutes les options de configuration | `MistralTranslator.configure` |
|
58
|
+
| [Méthodes](api-reference/methods.md) | Documentation complète des méthodes | API publique |
|
59
|
+
| [Erreurs](api-reference/errors.md) | Types d'erreurs et codes de gestion | `rescue` patterns |
|
60
|
+
| [Callbacks](api-reference/callbacks.md) | Événements et hooks personnalisés | Monitoring custom |
|
61
|
+
|
62
|
+
### 💻 Exemples Pratiques
|
63
|
+
|
64
|
+
| Fichier | Description | Cas d'Usage |
|
65
|
+
| --------------------------------------------------- | --------------------------------- | --------------- |
|
66
|
+
| [Usage de Base](../examples/basic_usage.rb) | Script simple avec commentaires | Premier projet |
|
67
|
+
| [Modèle Rails](../examples/rails-model.rb) | Modèle complet avec traductions | App Rails |
|
68
|
+
| [Job de Traitement](../examples/batch-job.rb) | Job Sidekiq pour batch | Production |
|
69
|
+
| [Setup Monitoring](../examples/monitoring-setup.rb) | Configuration complète monitoring | Ops & Analytics |
|
70
|
+
|
71
|
+
---
|
72
|
+
|
73
|
+
## 🎯 Cas d'Usage Principaux
|
74
|
+
|
75
|
+
### 🌐 **Applications Multilingues**
|
76
|
+
|
77
|
+
- E-commerce international
|
78
|
+
- Sites web multilingues
|
79
|
+
- Applications SaaS globales
|
80
|
+
- Documentation technique
|
81
|
+
|
82
|
+
### 📝 **Traitement de Contenu**
|
83
|
+
|
84
|
+
- Résumés automatiques d'articles
|
85
|
+
- Synthèse de rapports
|
86
|
+
- Newsletter multilingues
|
87
|
+
- Support client automatisé
|
88
|
+
|
89
|
+
### 🔧 **Intégration Système**
|
90
|
+
|
91
|
+
- CMS multilingues
|
92
|
+
- APIs de traduction
|
93
|
+
- Workflows de contenu
|
94
|
+
- Automation marketing
|
95
|
+
|
96
|
+
---
|
97
|
+
|
98
|
+
## 🏃♂️ Parcours Recommandés
|
99
|
+
|
100
|
+
### **👶 Débutant - Premiers Pas**
|
101
|
+
|
102
|
+
1. [Installation](installation.md) - Installer et configurer
|
103
|
+
2. [Guide de Démarrage](getting-started.md) - Premiers exemples
|
104
|
+
3. [Exemples de Base](../examples/basic_usage.rb) - Code pratique
|
105
|
+
|
106
|
+
### **⚡ Développeur Rails**
|
107
|
+
|
108
|
+
1. [Configuration Rails](rails-integration/setup.md) - Setup Rails
|
109
|
+
2. [Adaptateurs](rails-integration/adapters.md) - Mobility/Globalize
|
110
|
+
3. [Modèle Rails](../examples/rails-model.rb) - Exemple complet
|
111
|
+
|
112
|
+
### **🚀 Usage Production**
|
113
|
+
|
114
|
+
1. [Gestion des Erreurs](advanced-usage/error-handling.md) - Robustesse
|
115
|
+
2. [Monitoring](advanced-usage/monitoring.md) - Observabilité
|
116
|
+
3. [Jobs Asynchrones](rails-integration/jobs.md) - Scalabilité
|
117
|
+
|
118
|
+
### **📊 Analytics & Ops**
|
119
|
+
|
120
|
+
1. [Monitoring](advanced-usage/monitoring.md) - Métriques
|
121
|
+
2. [Setup Monitoring](../examples/monitoring-setup.rb) - Configuration
|
122
|
+
3. [API Référence](api-reference/configuration.md) - Tuning avancé
|
123
|
+
|
124
|
+
---
|
125
|
+
|
126
|
+
## 🆘 Aide et Support
|
127
|
+
|
128
|
+
- **🐛 Problème ?** → Consultez [Gestion des Erreurs](advanced-usage/error-handling.md)
|
129
|
+
- **⚙️ Configuration ?** → Voir [API Configuration](api-reference/configuration.md)
|
130
|
+
- **🛤️ Rails ?** → Section [Intégration Rails](rails-integration/setup.md)
|
131
|
+
- **📈 Performance ?** → Guide [Monitoring](advanced-usage/monitoring.md)
|
132
|
+
|
133
|
+
## 🎯 Navigation Rapide
|
134
|
+
|
135
|
+
**Recherche par fonctionnalité :**
|
136
|
+
|
137
|
+
- **Traduction simple** → [Getting Started](getting-started.md#traduction-simple)
|
138
|
+
- **Traduction HTML** → [Traductions Avancées](advanced-usage/translations.md#html-preservation)
|
139
|
+
- **Résumés** → [Résumés Intelligents](advanced-usage/summarization.md)
|
140
|
+
- **Batch processing** → [Traitement par Lot](advanced-usage/batch-processing.md)
|
141
|
+
- **Intégration Mobility** → [Adaptateurs](rails-integration/adapters.md#mobility)
|
142
|
+
- **Jobs Sidekiq** → [Jobs Asynchrones](rails-integration/jobs.md#sidekiq)
|
143
|
+
- **Dashboard admin** → [Controllers](rails-integration/controllers.md#dashboard)
|
144
|
+
|
145
|
+
**Par niveau de complexité :**
|
146
|
+
|
147
|
+
- 🟢 **Facile** : Installation, Getting Started, Exemples
|
148
|
+
- 🟡 **Moyen** : Traductions Avancées, Rails Setup, Jobs
|
149
|
+
- 🔴 **Avancé** : Error Handling, Monitoring, API Référence
|
150
|
+
|
151
|
+
---
|
152
|
+
|
153
|
+
_📝 Cette documentation est maintenue et mise à jour régulièrement. Pour des suggestions d'amélioration, n'hésitez pas à contribuer !_
|
@@ -0,0 +1,158 @@
|
|
1
|
+
> **Navigation :** [🏠 Home](README.md) • [📖 API Reference](api-reference/methods.md) • [⚡ Advanced Usage](advanced-usage/translations.md) • [🛤️ Rails Integration](rails-integration/setup.md)
|
2
|
+
|
3
|
+
---
|
4
|
+
|
5
|
+
# Traitement par Lot (Batch)
|
6
|
+
|
7
|
+
Optimisez vos traductions avec le traitement par lot et les traductions multiples.
|
8
|
+
|
9
|
+
## 📦 Batch Basique
|
10
|
+
|
11
|
+
```ruby
|
12
|
+
texts = ["Bonjour", "Comment ça va ?", "Au revoir"]
|
13
|
+
|
14
|
+
translator = MistralTranslator::Translator.new
|
15
|
+
results = translator.translate_batch(texts, from: "fr", to: "en")
|
16
|
+
|
17
|
+
results.each { |index, translation| puts "#{index}: #{translation}" }
|
18
|
+
# => 0: Hello
|
19
|
+
# => 1: How are you?
|
20
|
+
# => 2: Goodbye
|
21
|
+
```
|
22
|
+
|
23
|
+
## 🌍 Multi-langues
|
24
|
+
|
25
|
+
```ruby
|
26
|
+
# Vers plusieurs langues simultanément
|
27
|
+
results = translator.translate_to_multiple(
|
28
|
+
"Bienvenue",
|
29
|
+
from: "fr",
|
30
|
+
to: ["en", "es", "de", "it"],
|
31
|
+
use_batch: true # Optimisation
|
32
|
+
)
|
33
|
+
# => {"en" => "Welcome", "es" => "Bienvenido", ...}
|
34
|
+
```
|
35
|
+
|
36
|
+
## ⚡ Avec Gestion d'Erreurs
|
37
|
+
|
38
|
+
```ruby
|
39
|
+
# Fallback automatique en cas d'échec
|
40
|
+
results = MistralTranslator::Helpers.translate_batch_with_fallback(
|
41
|
+
texts,
|
42
|
+
from: "fr",
|
43
|
+
to: "en",
|
44
|
+
fallback_strategy: :individual # Retry individuellement
|
45
|
+
)
|
46
|
+
|
47
|
+
results.each do |index, result|
|
48
|
+
if result.is_a?(Hash) && result[:error]
|
49
|
+
puts "❌ Erreur #{index}: #{result[:error]}"
|
50
|
+
else
|
51
|
+
puts "✅ #{index}: #{result}"
|
52
|
+
end
|
53
|
+
end
|
54
|
+
```
|
55
|
+
|
56
|
+
## 📊 Avec Progression
|
57
|
+
|
58
|
+
```ruby
|
59
|
+
# Pour gros volumes
|
60
|
+
MistralTranslator::Helpers.translate_with_progress(
|
61
|
+
large_texts.each_with_index.to_h,
|
62
|
+
from: "fr",
|
63
|
+
to: "en"
|
64
|
+
) do |current, total, key, result|
|
65
|
+
progress = (current.to_f / total * 100).round(1)
|
66
|
+
puts "📈 [#{progress}%] #{key}"
|
67
|
+
end
|
68
|
+
```
|
69
|
+
|
70
|
+
## 🚦 Rate Limiting
|
71
|
+
|
72
|
+
```ruby
|
73
|
+
# Délai intelligent entre batches
|
74
|
+
def process_large_batch(texts, batch_size: 10)
|
75
|
+
texts.each_slice(batch_size).with_index do |batch, i|
|
76
|
+
results = translator.translate_batch(batch, from: "fr", to: "en")
|
77
|
+
|
78
|
+
# Pause entre batches (sauf le dernier)
|
79
|
+
sleep(2) unless i == (texts.size / batch_size.to_f).ceil - 1
|
80
|
+
end
|
81
|
+
end
|
82
|
+
```
|
83
|
+
|
84
|
+
## 💾 Avec Cache
|
85
|
+
|
86
|
+
```ruby
|
87
|
+
def cached_batch_translate(texts, from:, to:)
|
88
|
+
results = []
|
89
|
+
to_translate = []
|
90
|
+
|
91
|
+
# Vérifier le cache
|
92
|
+
texts.each_with_index do |text, index|
|
93
|
+
cache_key = "translation:#{Digest::MD5.hexdigest(text)}:#{from}:#{to}"
|
94
|
+
cached = Rails.cache.read(cache_key)
|
95
|
+
|
96
|
+
if cached
|
97
|
+
results[index] = cached
|
98
|
+
else
|
99
|
+
to_translate << { text: text, index: index, cache_key: cache_key }
|
100
|
+
end
|
101
|
+
end
|
102
|
+
|
103
|
+
# Traduire seulement ce qui n'est pas en cache
|
104
|
+
unless to_translate.empty?
|
105
|
+
fresh_results = translator.translate_batch(
|
106
|
+
to_translate.map { |item| item[:text] },
|
107
|
+
from: from, to: to
|
108
|
+
)
|
109
|
+
|
110
|
+
# Sauver en cache
|
111
|
+
fresh_results.each do |batch_index, translation|
|
112
|
+
original_index = to_translate[batch_index][:index]
|
113
|
+
cache_key = to_translate[batch_index][:cache_key]
|
114
|
+
|
115
|
+
Rails.cache.write(cache_key, translation, expires_in: 24.hours)
|
116
|
+
results[original_index] = translation
|
117
|
+
end
|
118
|
+
end
|
119
|
+
|
120
|
+
results
|
121
|
+
end
|
122
|
+
```
|
123
|
+
|
124
|
+
## 📈 Configuration Batch
|
125
|
+
|
126
|
+
```ruby
|
127
|
+
MistralTranslator.configure do |config|
|
128
|
+
config.retry_delays = [1, 3, 6] # Plus rapide pour batch
|
129
|
+
|
130
|
+
config.on_batch_complete = ->(size, duration, success, errors) {
|
131
|
+
rate = (success.to_f / size * 100).round(1)
|
132
|
+
puts "📊 Batch: #{success}/#{size} (#{rate}%) en #{duration.round(2)}s"
|
133
|
+
}
|
134
|
+
end
|
135
|
+
```
|
136
|
+
|
137
|
+
## 🎯 Patterns Recommandés
|
138
|
+
|
139
|
+
**Petits volumes (< 50 textes) :**
|
140
|
+
|
141
|
+
- Batch simple sans optimisation
|
142
|
+
|
143
|
+
**Moyens volumes (50-500 textes) :**
|
144
|
+
|
145
|
+
- Batch avec cache + rate limiting
|
146
|
+
|
147
|
+
**Gros volumes (> 500 textes) :**
|
148
|
+
|
149
|
+
- Jobs asynchrones + progression + cache
|
150
|
+
|
151
|
+
**Multi-langues :**
|
152
|
+
|
153
|
+
- `use_batch: true` pour optimisation API
|
154
|
+
|
155
|
+
---
|
156
|
+
|
157
|
+
**Advanced Usage Navigation:**
|
158
|
+
[← Translations](advanced-usage/translations.md) | [Batch Processing](advanced-usage/batch-processing.md) | [Error Handling](advanced-usage/error-handling.md) | [Monitoring](advanced-usage/monitoring.md) | [Summarization](advanced-usage/summarization.md) →
|
@@ -0,0 +1,106 @@
|
|
1
|
+
> **Navigation :** [🏠 Home](README.md) • [📖 API Reference](api-reference/methods.md) • [⚡ Advanced Usage](advanced-usage/translations.md) • [🛤️ Rails Integration](rails-integration/setup.md)
|
2
|
+
|
3
|
+
---
|
4
|
+
|
5
|
+
# Gestion des Erreurs
|
6
|
+
|
7
|
+
Patterns et stratégies pour gérer les erreurs de traduction de façon robuste.
|
8
|
+
|
9
|
+
## 🚨 Types d'Erreurs
|
10
|
+
|
11
|
+
### Erreurs de Configuration
|
12
|
+
|
13
|
+
- **`ConfigurationError`** : Clé API manquante
|
14
|
+
- **`AuthenticationError`** : Clé API invalide
|
15
|
+
|
16
|
+
### Erreurs d'API
|
17
|
+
|
18
|
+
- **`RateLimitError`** : Quota dépassé
|
19
|
+
- **`ApiError`** : Erreurs serveur (500, 502, 503)
|
20
|
+
- **`InvalidResponseError`** : Réponse malformée
|
21
|
+
|
22
|
+
### Erreurs de Contenu
|
23
|
+
|
24
|
+
- **`EmptyTranslationError`** : Traduction vide
|
25
|
+
- **`UnsupportedLanguageError`** : Langue non reconnue
|
26
|
+
|
27
|
+
## ⚡ Stratégies de Retry
|
28
|
+
|
29
|
+
### Configuration
|
30
|
+
|
31
|
+
```ruby
|
32
|
+
MistralTranslator.configure do |config|
|
33
|
+
config.retry_delays = [1, 3, 6, 12] # Délais exponentiels
|
34
|
+
end
|
35
|
+
```
|
36
|
+
|
37
|
+
### Retry par Type d'Erreur
|
38
|
+
|
39
|
+
- **Rate Limit** → Délai long (30s, 60s)
|
40
|
+
- **Erreur Serveur** → Délai court (2s, 4s)
|
41
|
+
- **Auth/Config** → Pas de retry
|
42
|
+
- **Response Invalide** → 1-2 tentatives max
|
43
|
+
|
44
|
+
## 🔄 Circuit Breaker
|
45
|
+
|
46
|
+
### Principe
|
47
|
+
|
48
|
+
```
|
49
|
+
FERMÉ → OUVERT → DEMI-OUVERT → FERMÉ
|
50
|
+
```
|
51
|
+
|
52
|
+
- **FERMÉ** : Fonctionnement normal
|
53
|
+
- **OUVERT** : Échecs répétés → court-circuite
|
54
|
+
- **DEMI-OUVERT** : Test après timeout
|
55
|
+
|
56
|
+
### Paramètres
|
57
|
+
|
58
|
+
- Seuil : 5 erreurs consécutives
|
59
|
+
- Timeout : 5 minutes
|
60
|
+
- Reset : 3 succès consécutifs
|
61
|
+
|
62
|
+
## 🛡️ Fallback Strategies
|
63
|
+
|
64
|
+
### Cascade Recommandée
|
65
|
+
|
66
|
+
1. API Mistral
|
67
|
+
2. Cache de traductions
|
68
|
+
3. Service alternatif
|
69
|
+
4. Texte original
|
70
|
+
|
71
|
+
### Validation Qualité
|
72
|
+
|
73
|
+
- Ratio longueur : 0.3x - 3x de l'original
|
74
|
+
- Pas identique à l'original
|
75
|
+
- Encodage correct
|
76
|
+
|
77
|
+
## 📊 Monitoring
|
78
|
+
|
79
|
+
### Métriques Clés
|
80
|
+
|
81
|
+
- Taux d'erreur global (< 5%)
|
82
|
+
- Types d'erreurs par fréquence
|
83
|
+
- Efficacité des fallbacks
|
84
|
+
|
85
|
+
### Alertes
|
86
|
+
|
87
|
+
```yaml
|
88
|
+
Critique:
|
89
|
+
- Auth échoue
|
90
|
+
- Erreurs > 20% sur 5min
|
91
|
+
|
92
|
+
Important:
|
93
|
+
- Rate limit > 10/h
|
94
|
+
- Circuit breaker ouvert
|
95
|
+
```
|
96
|
+
|
97
|
+
## 🎯 Configuration par Environnement
|
98
|
+
|
99
|
+
**Development** : Logs verbeux, retry rapides
|
100
|
+
**Test** : Mocks d'erreurs, validation timeouts
|
101
|
+
**Production** : Circuit breaker, fallbacks gracieux
|
102
|
+
|
103
|
+
---
|
104
|
+
|
105
|
+
**Advanced Usage Navigation:**
|
106
|
+
[← Translations](advanced-usage/translations.md) | [Batch Processing](advanced-usage/batch-processing.md) | [Error Handling](advanced-usage/error-handling.md) | [Monitoring](advanced-usage/monitoring.md) | [Summarization](advanced-usage/summarization.md) →
|
@@ -0,0 +1,133 @@
|
|
1
|
+
> **Navigation :** [🏠 Home](README.md) • [📖 API Reference](api-reference/methods.md) • [⚡ Advanced Usage](advanced-usage/translations.md) • [🛤️ Rails Integration](rails-integration/setup.md)
|
2
|
+
|
3
|
+
---
|
4
|
+
|
5
|
+
# Monitoring et Métriques
|
6
|
+
|
7
|
+
Surveillez et optimisez vos traductions avec des métriques pertinentes et des alertes intelligentes.
|
8
|
+
|
9
|
+
## 📊 Métriques Essentielles
|
10
|
+
|
11
|
+
### Configuration de base
|
12
|
+
|
13
|
+
```ruby
|
14
|
+
MistralTranslator.configure do |config|
|
15
|
+
config.enable_metrics = true
|
16
|
+
|
17
|
+
# Callbacks pour vos systèmes de monitoring
|
18
|
+
config.on_translation_complete = ->(from, to, orig_len, trans_len, duration) {
|
19
|
+
# Intégrer avec votre système (StatsD, DataDog, etc.)
|
20
|
+
}
|
21
|
+
end
|
22
|
+
```
|
23
|
+
|
24
|
+
### Métriques clés à suivre
|
25
|
+
|
26
|
+
**Performance :**
|
27
|
+
|
28
|
+
- Temps de réponse moyen/médian/P95
|
29
|
+
- Throughput (traductions/minute)
|
30
|
+
- Taille des textes traités
|
31
|
+
|
32
|
+
**Qualité :**
|
33
|
+
|
34
|
+
- Taux de succès vs erreurs
|
35
|
+
- Types d'erreurs (auth, rate limit, timeout)
|
36
|
+
- Score de confiance moyen
|
37
|
+
|
38
|
+
**Usage :**
|
39
|
+
|
40
|
+
- Paires de langues populaires
|
41
|
+
- Volume par heure/jour/mois
|
42
|
+
- Coût estimé
|
43
|
+
|
44
|
+
## 🚨 Alertes Recommandées
|
45
|
+
|
46
|
+
### Alertes Critiques
|
47
|
+
|
48
|
+
- **Taux d'erreur > 10%** sur 5 minutes
|
49
|
+
- **Temps de réponse > 30s** de façon répétée
|
50
|
+
- **Erreurs d'authentification** (problème de clé API)
|
51
|
+
|
52
|
+
### Alertes d'Information
|
53
|
+
|
54
|
+
- **Rate limit atteint** (ajuster le throttling)
|
55
|
+
- **Pic d'usage inhabituel** (analyser la cause)
|
56
|
+
- **Nouvelle paire de langues** utilisée
|
57
|
+
|
58
|
+
## 📈 Dashboard Suggéré
|
59
|
+
|
60
|
+
### Vue d'ensemble
|
61
|
+
|
62
|
+
```
|
63
|
+
┌─────────────────┬─────────────────┬─────────────────┐
|
64
|
+
│ Traductions/h │ Temps moyen │ Taux de succès │
|
65
|
+
│ 250 │ 1.2s │ 99.2% │
|
66
|
+
├─────────────────┼─────────────────┼─────────────────┤
|
67
|
+
│ Top langues │ Erreurs/h │ Coût du jour │
|
68
|
+
│ fr→en (45%) │ 2 │ $12.34 │
|
69
|
+
│ en→es (23%) │ │ │
|
70
|
+
└─────────────────┴─────────────────┴─────────────────┘
|
71
|
+
```
|
72
|
+
|
73
|
+
### Graphiques utiles
|
74
|
+
|
75
|
+
- **Timeline** : Volume de traductions dans le temps
|
76
|
+
- **Heatmap** : Paires de langues par popularité
|
77
|
+
- **Latency** : Distribution des temps de réponse
|
78
|
+
- **Errors** : Types d'erreurs par période
|
79
|
+
|
80
|
+
## 🔍 Logging Efficace
|
81
|
+
|
82
|
+
### Structure de logs recommandée
|
83
|
+
|
84
|
+
```
|
85
|
+
[TIMESTAMP] [LEVEL] [MistralTranslator] [OPERATION] from=fr to=en chars=150 duration=1.2s status=success
|
86
|
+
[TIMESTAMP] [ERROR] [MistralTranslator] [TRANSLATE] from=fr to=en error=rate_limit attempt=2
|
87
|
+
```
|
88
|
+
|
89
|
+
### Niveaux de log par environnement
|
90
|
+
|
91
|
+
- **Development** : DEBUG (tout)
|
92
|
+
- **Staging** : INFO (succès + erreurs)
|
93
|
+
- **Production** : WARN (erreurs + rate limits)
|
94
|
+
|
95
|
+
## ⚡ Optimisation Basée sur les Métriques
|
96
|
+
|
97
|
+
### Patterns à identifier
|
98
|
+
|
99
|
+
**Rate limiting :**
|
100
|
+
|
101
|
+
- Si beaucoup de rate limits → ajuster les délais
|
102
|
+
- Répartir les requêtes dans le temps
|
103
|
+
|
104
|
+
**Performance :**
|
105
|
+
|
106
|
+
- Textes longs = temps longs → découper si possible
|
107
|
+
- Certaines paires de langues plus lentes
|
108
|
+
|
109
|
+
**Usage :**
|
110
|
+
|
111
|
+
- Cache les traductions populaires
|
112
|
+
- Pre-traduire le contenu critique
|
113
|
+
|
114
|
+
### Seuils d'alerte suggérés
|
115
|
+
|
116
|
+
```yaml
|
117
|
+
performance:
|
118
|
+
response_time_p95: 10s
|
119
|
+
error_rate_5min: 5%
|
120
|
+
|
121
|
+
capacity:
|
122
|
+
requests_per_minute: 50
|
123
|
+
daily_cost: $100
|
124
|
+
|
125
|
+
quality:
|
126
|
+
confidence_score_avg: 0.7
|
127
|
+
empty_translations: 1%
|
128
|
+
```
|
129
|
+
|
130
|
+
---
|
131
|
+
|
132
|
+
**Advanced Usage Navigation:**
|
133
|
+
[← Translations](advanced-usage/translations.md) | [Batch Processing](advanced-usage/batch-processing.md) | [Error Handling](advanced-usage/error-handling.md) | [Monitoring](advanced-usage/monitoring.md) | [Summarization](advanced-usage/summarization.md) →
|
@@ -0,0 +1,86 @@
|
|
1
|
+
> **Navigation :** [🏠 Home](README.md) • [📖 API Reference](api-reference/methods.md) • [⚡ Advanced Usage](advanced-usage/translations.md) • [🛤️ Rails Integration](rails-integration/setup.md)
|
2
|
+
|
3
|
+
---
|
4
|
+
|
5
|
+
# Résumés Intelligents
|
6
|
+
|
7
|
+
Résumés automatiques, multi-niveaux et multilingues.
|
8
|
+
|
9
|
+
## 📝 Résumé Simple
|
10
|
+
|
11
|
+
```ruby
|
12
|
+
summarizer = MistralTranslator::Summarizer.new
|
13
|
+
|
14
|
+
summary = summarizer.summarize(
|
15
|
+
long_text,
|
16
|
+
language: "fr",
|
17
|
+
max_words: 100
|
18
|
+
)
|
19
|
+
```
|
20
|
+
|
21
|
+
## 🌍 Résumé + Traduction
|
22
|
+
|
23
|
+
```ruby
|
24
|
+
# Résume ET traduit en une opération
|
25
|
+
french_summary = summarizer.summarize_and_translate(
|
26
|
+
english_article,
|
27
|
+
from: "en",
|
28
|
+
to: "fr",
|
29
|
+
max_words: 150
|
30
|
+
)
|
31
|
+
```
|
32
|
+
|
33
|
+
## 📊 Multi-niveaux
|
34
|
+
|
35
|
+
```ruby
|
36
|
+
summaries = summarizer.summarize_tiered(
|
37
|
+
article,
|
38
|
+
language: "fr",
|
39
|
+
short: 50, # Tweet
|
40
|
+
medium: 150, # Paragraphe
|
41
|
+
long: 400 # Article court
|
42
|
+
)
|
43
|
+
|
44
|
+
puts summaries[:short]
|
45
|
+
puts summaries[:medium]
|
46
|
+
puts summaries[:long]
|
47
|
+
```
|
48
|
+
|
49
|
+
## 🗺️ Multi-langues
|
50
|
+
|
51
|
+
```ruby
|
52
|
+
results = summarizer.summarize_to_multiple(
|
53
|
+
document,
|
54
|
+
languages: ["fr", "en", "es"],
|
55
|
+
max_words: 200
|
56
|
+
)
|
57
|
+
# => { "fr" => "résumé...", "en" => "summary...", "es" => "resumen..." }
|
58
|
+
```
|
59
|
+
|
60
|
+
## 🎯 Styles de Résumé
|
61
|
+
|
62
|
+
```ruby
|
63
|
+
# Différents styles selon l'usage
|
64
|
+
summarizer.summarize(content, context: "Executive summary, key metrics")
|
65
|
+
summarizer.summarize(content, context: "Social media, engaging tone")
|
66
|
+
summarizer.summarize(content, context: "Technical documentation")
|
67
|
+
```
|
68
|
+
|
69
|
+
## 📈 Longueurs Recommandées
|
70
|
+
|
71
|
+
**Selon taille du contenu :**
|
72
|
+
|
73
|
+
- 0-200 mots → Résumé 30-50 mots
|
74
|
+
- 200-800 mots → Résumé 50-100 mots
|
75
|
+
- 800+ mots → Résumé 100-200 mots
|
76
|
+
|
77
|
+
**Selon usage :**
|
78
|
+
|
79
|
+
- Tweet → 50 mots max
|
80
|
+
- Meta description → 150 mots max
|
81
|
+
- Résumé exécutif → 200-400 mots
|
82
|
+
|
83
|
+
---
|
84
|
+
|
85
|
+
**Advanced Usage Navigation:**
|
86
|
+
[← Translations](advanced-usage/translations.md) | [Batch Processing](advanced-usage/batch-processing.md) | [Error Handling](advanced-usage/error-handling.md) | [Monitoring](advanced-usage/monitoring.md) | [Summarization](advanced-usage/summarization.md) →
|