187 lines
6.7 KiB
Markdown
187 lines
6.7 KiB
Markdown
# API made with Strapi
|
|
|
|
<p align="center">
|
|
<a href="https://liberapay.com/OKI/donate/">
|
|
<img src="https://img.shields.io/liberapay/receives/OKI.svg?logo=liberapay">
|
|
<img src="https://img.shields.io/liberapay/patrons/OKI.svg?logo=liberapay">
|
|
<img src="https://img.shields.io/liberapay/goal/OKI.svg?logo=liberapay">
|
|
</a>
|
|
</p>
|
|
|
|
## Prérequis
|
|
- Node >= 16
|
|
- Npm ou Yarn
|
|
|
|
## Variables d'environnement
|
|
- Copier le contenu du fichier `.env.sample` dans un nouveau fichier `.env`
|
|
```
|
|
cp .env.sample .env
|
|
```
|
|
|
|
`STRAPI_URL` sera utile en production uniquement. Cette variable fait référence à l'url du site de production *(exemple : `https://api.mon-site.fr`)*.
|
|
|
|
`STRAPI_ADMIN_URL` fait référence à la route pour accéder à l'espace d'administration *(par défaut : `/admin`)* .
|
|
|
|
## Générer les clés nécessaires :
|
|
|
|
Ces variables d'environnement sont obligatoires :
|
|
|
|
- **APP_KEYS**
|
|
- **API_TOKEN_SALT**
|
|
- **ADMIN_JWT_SECRET**
|
|
- **JWT_SECRET** *(générée automatique si non renseignée)*
|
|
|
|
Afin de les renseigner, vous pouvez générer des clés en passant par node :
|
|
|
|
```bash
|
|
node
|
|
```
|
|
|
|
Une fois dans la console node, tapez :
|
|
|
|
```bash
|
|
crypto.randomBytes(16).toString('base64')
|
|
```
|
|
*retourne par exemple : 'BwUANVKSfenqAs1eFBHDIA=='*
|
|
|
|
Générez une clé pour chaque variable et ajoutez les au fichier .env.
|
|
La varialbe APP_KEYS peut en contenir plusieurs séparées, par une virgule :
|
|
*APP_KEYS=BwUANVKSfenqAs1eFBHDIA==,GiznuBga8kH0ZcOM5YO85w==*
|
|
|
|
Si la variable JWT_SECRET n'est pas renseignée, elle est générée automatiquement par Strapi.
|
|
|
|
## Installation des dépendances & lancement du serveur
|
|
|
|
```
|
|
yarn && yarn build && yarn dev
|
|
```
|
|
|
|
## Tokens API
|
|
|
|
Les endpoints marqués ⚙️ **Token requis** nécessitent un token API Strapi.
|
|
|
|
**Créer le token** : Administration Strapi → *Settings → API Tokens → Create new API Token*
|
|
|
|
| Endpoint | Type de token | Permissions requises |
|
|
|----------|---------------|----------------------|
|
|
| `GET /paroles/export` | Custom | Parole → `export` |
|
|
| `POST /paroles/bulk-translate` | Custom | Parole → `bulkTranslate` |
|
|
|
|
Pour un token couvrant les deux endpoints, créer un token de type **Custom** et cocher dans la section *Parole* : `export` et `bulkTranslate`.
|
|
|
|
Le token est à passer dans le header HTTP :
|
|
```
|
|
Authorization: Bearer <token>
|
|
```
|
|
|
|
---
|
|
|
|
## Point d'accès
|
|
|
|
### `/awtis`
|
|
- `GET` : Lister tous les artistes
|
|
|
|
### `/awtis/{id}`
|
|
- `GET` : Récupérer les informations d'un artiste
|
|
|
|
### `/awtis/count`
|
|
- `GET` : Récupère le nombre d'artiste
|
|
___
|
|
|
|
### `/paroles`
|
|
- `GET` : Lister tous les textes
|
|
|
|
### `/paroles/{id}`
|
|
- `GET` : Récupérer les informations d'un texte
|
|
|
|
### `/paroles/count`
|
|
- `GET` : Récupère le nombre de texte
|
|
|
|
### `/paroles/bulk-translate` ⚙️ Token requis
|
|
- `POST` : Traduit automatiquement via DeepL toutes les paroles ayant une source française (`traductions.francais` ou `langueSource: fr`) vers les langues manquantes (EN, ES, DE, IT). Ne modifie pas les traductions déjà existantes.
|
|
|
|
**Réponse :**
|
|
```json
|
|
{"translated": 42, "skipped": 18, "errors": []}
|
|
```
|
|
|
|
| Champ | Description |
|
|
|-------|-------------|
|
|
| `translated` | Nombre de traductions ajoutées |
|
|
| `skipped` | Paroles ignorées (pas de source FR ou déjà complètes) |
|
|
| `errors` | Erreurs DeepL avec `documentId`, `titre` et `lang` |
|
|
|
|
**Exemple :**
|
|
```bash
|
|
curl -X POST -H "Authorization: Bearer <token>" \
|
|
"https://api.pawol.nu/api/paroles/bulk-translate"
|
|
```
|
|
|
|
___
|
|
|
|
### `/paroles/export` ⚙️ Token requis
|
|
- `GET` : Exporter les paroles et traductions au format JSONL ou JSON pour l'entraînement de modèles LLM
|
|
|
|
**Paramètres de requête :**
|
|
|
|
| Paramètre | Valeurs acceptées | Défaut | Description |
|
|
|-----------|-------------------|--------|-------------|
|
|
| `type` | `pairs` \| `instruct` | `pairs` | Format des exemples d'entraînement |
|
|
| `lang` | `fr,en,es,de,it` | toutes | Langues cibles à inclure (séparées par des virgules) |
|
|
| `format` | `jsonl` \| `json` | `jsonl` | Format de la réponse |
|
|
|
|
**Type `pairs`** — corpus parallèle source/cible, adapté aux modèles de traduction :
|
|
```json
|
|
{"source_lang":"ka","target_lang":"fr","source":"Mwen ka palé épi ou…","target":"Je suis en train de te parler…","title":"Titre","artists":["Artiste"]}
|
|
```
|
|
|
|
**Type `instruct`** — format instruction/chat, adapté au fine-tuning de modèles d'instruction :
|
|
```json
|
|
{"messages":[{"role":"system","content":"Tu es un expert en langue KA…"},{"role":"user","content":"Tradui an fransé :\n\nMwen ka palé épi ou…"},{"role":"assistant","content":"Je suis en train de te parler…"}]}
|
|
```
|
|
|
|
**Format `jsonl`** : la première ligne contient les métadonnées (champ `_metadata: true`). Pour les filtrer :
|
|
```bash
|
|
jq 'select(._metadata | not)' export.jsonl
|
|
```
|
|
|
|
**Métadonnées incluses** (`_metadata: true` en JSONL, clé `metadata` en JSON) :
|
|
|
|
| Champ | Description |
|
|
|-------|-------------|
|
|
| `exported_at` | Horodatage de l'export |
|
|
| `total_paroles` | Nombre de paroles traitées |
|
|
| `total_pairs` | Nombre d'exemples d'entraînement générés |
|
|
| `languages` | Nombre de paires par langue |
|
|
| `missing_translations` | Paroles avec des traductions manquantes, par langue |
|
|
| `non_ka_transcriptions` | Paroles dont la transcription est suspectée d'être dans une autre langue (ex. français) |
|
|
|
|
**Exemple :**
|
|
```bash
|
|
curl -H "Authorization: Bearer <token>" \
|
|
"https://api.pawol.nu/api/paroles/export?type=instruct&lang=fr,en&format=jsonl" \
|
|
-o dataset.jsonl
|
|
```
|
|
|
|
## License
|
|
|
|
Copyright (C) 2024 Cédric Famibelle-Pronzola & ORGANISATION KA INTERNATIONALE (OKI)
|
|
|
|
|
|
### FR
|
|
|
|
Ce programme est un logiciel libre : vous pouvez le redistribuer et/ou le modifier selon les termes de la licence publique générale GNU Affero publiée par la Free Software Foundation, soit la version 3 de la licence, soit (à votre choix) toute version ultérieure.
|
|
|
|
Ce programme est distribué dans l'espoir qu'il sera utile, mais SANS AUCUNE GARANTIE ; sans même la garantie implicite de COMMERCIALISATION ou d'ADAPTATION À UN USAGE PARTICULIER. Voir la licence publique générale GNU Affero pour plus de détails.
|
|
|
|
Vous devriez avoir reçu une copie de la licence publique générale GNU Affero avec ce programme. Si ce n'est pas le cas, consultez https://www.gnu.org/licenses/.
|
|
|
|
|
|
### EN
|
|
|
|
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
|
|
|
|
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
|
|
|
|
You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.
|