docs: guides d'utilisation, capture reelle et README ameliores
This commit is contained in:
@@ -0,0 +1,193 @@
|
||||
# 🔍 Guide Recherche, PDF & Excalidraw
|
||||
|
||||
ObsiGate va au-delà de la simple lecture : recherche puissante, rendu des
|
||||
documents riches (PDF, diagrammes) et indexation de leur contenu pour que tout
|
||||
soit retrouvable.
|
||||
|
||||
> **Public :** tous les utilisateurs
|
||||
> **Fiches techniques :** [`features/semantic-search.md`](../features/semantic-search.md) ·
|
||||
> [`features/pdf.md`](../features/pdf.md) · [`features/excalidraw.md`](../features/excalidraw.md)
|
||||
|
||||
---
|
||||
|
||||
## 1. Recherche plein texte (TF-IDF)
|
||||
|
||||
Le moteur d'ObsiGate s'appuie sur un **index inversé** et un scoring **TF-IDF**
|
||||
avec :
|
||||
|
||||
- **Boost titre** — une correspondance dans le titre pèse 3× plus.
|
||||
- **Normalisation des accents** — `resume` trouve `résumé`, `elephant` trouve `éléphant`.
|
||||
- **Stemming français** — les variantes des mots sont rapprochées.
|
||||
- **Snippets surlignés** — les termes trouvés sont mis en `<mark>` dans l'extrait.
|
||||
- **Facettes** — compteurs par vault et par tag sur les résultats.
|
||||
- **Pagination** — 50 résultats par page.
|
||||
- **Tri** — par pertinence (TF-IDF) ou par date de modification.
|
||||
- **Chips de filtres** — les filtres actifs apparaissent sous forme de puces retirables.
|
||||
- **Historique** — les 50 dernières recherches sont conservées en `localStorage`.
|
||||
|
||||
La recherche s'effectue **sans I/O disque** : le contenu est déjà en mémoire.
|
||||
|
||||
---
|
||||
|
||||
## 2. Syntaxe de requête
|
||||
|
||||
| Opérateur | Description | Exemple |
|
||||
|---|---|---|
|
||||
| `tag:<nom>` | Filtre par tag | `tag:recette docker` |
|
||||
| `#<nom>` | Raccourci de tag | `#linux serveur` |
|
||||
| `vault:<nom>` | Filtre par vault | `vault:IT kubernetes` |
|
||||
| `title:<texte>` | Filtre par titre | `title:pizza` |
|
||||
| `path:<texte>` | Filtre par chemin | `path:recettes/soupes` |
|
||||
| `ext:<type>` | Filtre par type de fichier | `ext:md kubernetes` |
|
||||
| `"phrase exacte"` | Recherche d'une phrase | `tag:"multi mots"` |
|
||||
|
||||
Les opérateurs sont **combinables** :
|
||||
|
||||
```text
|
||||
tag:linux vault:IT ext:md serveur web
|
||||
```
|
||||
|
||||
Cette requête cherche « serveur web » dans les fichiers Markdown de la vault
|
||||
`IT` portant le tag `linux`.
|
||||
|
||||
### Filtres par extension
|
||||
|
||||
| Extension | Contenu |
|
||||
|---|---|
|
||||
| `ext:md` | Notes Markdown |
|
||||
| `ext:py`, `ext:sh`, `ext:js` | Scripts et code |
|
||||
| `ext:pdf` | Documents PDF (texte extrait) |
|
||||
| `ext:excalidraw` | Diagrammes Excalidraw (texte extrait) |
|
||||
|
||||
---
|
||||
|
||||
## 3. Autocomplétion et suggestions
|
||||
|
||||
- **`/api/suggest`** — suggère des titres de fichiers.
|
||||
- **`/api/tags/suggest`** — suggère des tags.
|
||||
- Navigation clavier : `↑` / `↓` puis `Entrée` ; `Échap` ferme les suggestions.
|
||||
|
||||
### Raccourcis de recherche
|
||||
|
||||
| Raccourci | Action |
|
||||
|---|---|
|
||||
| `Ctrl + K` / `Cmd + K` | Focaliser la barre de recherche |
|
||||
| `/` | Focaliser la recherche (hors champ texte) |
|
||||
| `↑` / `↓` | Naviguer dans les suggestions |
|
||||
| `Entrée` | Sélectionner la suggestion active ou lancer la recherche |
|
||||
| `Échap` | Fermer les suggestions / quitter la recherche |
|
||||
|
||||
Recherches sauvegardées et signets sont disponibles via l'API
|
||||
(`/api/saved-searches`, `/api/bookmarks`).
|
||||
|
||||
---
|
||||
|
||||
## 4. Recherche sémantique (optionnelle)
|
||||
|
||||
Au classement TF-IDF peut s'ajouter un classement **par embeddings**, fusionné
|
||||
via la méthode **RRF** (Reciprocal Rank Fusion). Activation : touche `~`
|
||||
(ou `Alt + S`) dans la recherche.
|
||||
|
||||
Deux modes :
|
||||
|
||||
1. **Sans dépendance** — un *embedder* par hachage fournit une base utilisable
|
||||
immédiatement.
|
||||
2. **Embeddings réels** — installez `backend/requirements-semantic.txt` et/ou
|
||||
renseignez les variables `OBSIGATE_EMBEDDING_*` pour utiliser
|
||||
`all-MiniLM-L6-v2`.
|
||||
|
||||
Détails et configuration :
|
||||
[`features/semantic-search.md`](../features/semantic-search.md).
|
||||
|
||||
---
|
||||
|
||||
## 5. Support PDF
|
||||
|
||||
### Lecture
|
||||
|
||||
Les fichiers PDF de vos vaults s'affichent **en ligne** dans le navigateur via le
|
||||
visualiseur PDF natif (iframe + `<embed>`). Le fichier est **streamé** en HTTP
|
||||
Range (`206 Partial Content`) : les gros PDF se chargent progressivement.
|
||||
|
||||
### Recherche
|
||||
|
||||
Le texte est **extrait à l'indexation** (`pypdf` / `pymupdf`), donc le contenu
|
||||
des PDF est recherchable via la recherche plein texte. Utilisez `ext:pdf` pour
|
||||
limiter les résultats aux PDF.
|
||||
|
||||
### Métadonnées
|
||||
|
||||
`GET /api/file/{vault}/pdf/info` renvoie les métadonnées (pages, titre, auteur)
|
||||
**sans transférer** le document.
|
||||
|
||||
```bash
|
||||
curl "http://localhost:2020/api/file/Recettes/pdf/info?path=menu.pdf"
|
||||
```
|
||||
|
||||
### Limites
|
||||
|
||||
- **Pas d'OCR** : les PDF scannés (images) ne sont pas recherchables.
|
||||
- Pas d'annotation ni d'édition du PDF lui-même.
|
||||
|
||||
---
|
||||
|
||||
## 6. Diagrammes Excalidraw
|
||||
|
||||
Les fichiers `.excalidraw` et `.excalidraw.md` (dont le format compressé du
|
||||
**plugin Obsidian Excalidraw**) s'ouvrent dans un **éditeur visuel Excalidraw
|
||||
complet**, dans une iframe sandboxée.
|
||||
|
||||
- **Dessin et édition** sans quitter ObsiGate.
|
||||
- **Sauvegarde automatique** (débounce 2 s) ou `Ctrl + S`.
|
||||
- **Thème** clair/sombre suivi automatiquement.
|
||||
- **Texte indexé** : le texte des éléments du diagramme est extrait à
|
||||
l'indexation et donc recherchable (`ext:excalidraw`).
|
||||
|
||||
Fiche technique : [`features/excalidraw.md`](../features/excalidraw.md).
|
||||
|
||||
---
|
||||
|
||||
## 7. Autres contenus riches
|
||||
|
||||
### Mermaid
|
||||
|
||||
Les blocs de code ` ```mermaid ` sont rendus en diagrammes interactifs (live
|
||||
preview, thèmes, zoom, plein écran, pré-processeur compatible syntaxe Obsidian).
|
||||
|
||||
### Images Obsidian
|
||||
|
||||
Toutes les syntaxes d'images sont supportées avec résolution intelligente en
|
||||
7 stratégies :
|
||||
|
||||
1. chemin absolu ;
|
||||
2. dossier d'attachements configuré (`VAULT_N_ATTACHMENTS_PATH`) ;
|
||||
3. index de démarrage (correspondance unique) ;
|
||||
4. même répertoire que la note ;
|
||||
5. racine de la vault ;
|
||||
6. index de démarrage (correspondance la plus proche) ;
|
||||
7. repli : `[image not found: fichier.ext]`.
|
||||
|
||||
Rescan manuel des attachements :
|
||||
|
||||
```bash
|
||||
curl -X POST "http://localhost:2020/api/attachments/rescan/Recettes"
|
||||
```
|
||||
|
||||
### Graphe et backlinks
|
||||
|
||||
- **Graphe** : vue force-directed (Barnes-Hut), filtres (tag, type), profondeur,
|
||||
mode focus, export PNG, aperçu au survol (`Ctrl + clic`).
|
||||
- **Backlinks** : `GET /api/file/{vault}/backlinks?path=…` liste les notes
|
||||
pointant vers un document.
|
||||
|
||||
---
|
||||
|
||||
## 8. Dépannage
|
||||
|
||||
| Symptôme | Piste |
|
||||
|---|---|
|
||||
| Un PDF ne s'affiche pas | Vérifier la taille (`OBSIGATE_PDF_MAX_SIZE_MB`, défaut 50 Mo) |
|
||||
| Le texte d'un PDF scanné n'est pas trouvé | Pas d'OCR : normal |
|
||||
| Une image reste introuvable | Configurer `VAULT_N_ATTACHMENTS_PATH`, puis rescan |
|
||||
| La recherche sémantique ne s'active pas | Vérifier le toggle `~` et `OBSIGATE_EMBEDDING_*` |
|
||||
| Résultats obsolètes | Forcer une réindexation : `GET /api/index/reload` |
|
||||
Reference in New Issue
Block a user