Mémoire des agents IA sous forme de graphe de connaissances : Cognee ingère des documents et des conversations (add), extrait les entités et les relations avec le LLM dans un graphe (cognify) et répond à des recherches sémantiques, dans le graphe et GraphRAG. Chaque jeu de données a son propre fichier de graphe et son schéma de vecteurs ; utilisateurs, locataires et permissions par jeu de données isolent les espaces. Les appels au LLM et aux plongements passent par la passerelle LiteLLM de la plateforme.
Généré depuis catalog/services/cognee.yaml : ne pas modifier à la main.
Résumé
| |
|---|
| Version | 1.6.6 |
| Usage | installer et configurer, configurer et connecter |
| Couche | fonctionnelle (catalogue IA) |
| Catégorie | Mémoire IA |
| Sous-catégorie | Graphe de connaissances et GraphRAG |
| Méthodes d'installation | python, podman |
| Connexion externe | non |
| Réservé au bac à sable | non |
Licence
| |
|---|
| Identifiant SPDX | Apache-2.0 |
| Politique de licence | licence socle (MIT ou Apache-2.0) |
| Exception de licence | - |
| Remarque de licence | Cognee 1.6.6 (tag v1.6.6, commit df2b4facd7c1, wheel cognee-1.6.6-py3-none-any.whl sha256 bee551bd81c8f619acfc345088a4601b694ff941b80feaee52e4e03a25834408), l'interface (cognee-frontend) et le serveur MCP (cognee-mcp 0.5.7) du même dépôt sous sa LICENSE Apache-2.0 ; LadybugDB 0.19.0 (moteur de graphe embarqué, dérivé de Kuzu) est sous MIT. Toutes les dépendances Python de la version sont sous licence OSI (MIT, BSD, Apache-2.0, ISC, MPL-2.0, PSF-2.0, Unlicense, LGPL-3.0 avec exceptions pour psycopg2). Cognee Cloud, l'extracteur de démonstration GLiNER, Neo4j, Neptune et les recettes cloud de distributed/deploy ne sont ni installés ni configurés. |
| Composant de la plateforme | cognee |
Paquets et artefacts
Un paquet que publie le projet du service (son image, son archive binaire, son paquet Python ou système) porte la licence du service ; un paquet tiers porte la licence écrite sur sa ligne, lue dans les métadonnées officielles du projet amont.
| Type | Paquet | Version | Licence | Détails |
|---|
| image de conteneur | docker.io/cognee/cognee | 1.6.6 | Apache-2.0 | clé d'image cognee, utilisée par api, condensé sha256:e3db1d4d2f4b8f1fa3cc74c7d8e01151f60ac0aa9e63957d277068c89e25970e |
| image de conteneur | docker.io/cognee/cognee-ui | 1.6.6 | Apache-2.0 | clé d'image cognee-ui, utilisée par ui, condensé sha256:dd569dab8646e5ee6568f2fa9ea4e928937594beda57f316bc243e4514e09e8d |
| image de conteneur | docker.io/cognee/cognee-mcp | main-df2b4fa | Apache-2.0 | clé d'image cognee-mcp, utilisée par mcp, condensé sha256:7b308820d37b21d8f64b2ec3db2fec6a12aee13c92e442b7ee3b240e027d7bdc |
| paquet Python | cognee[api,postgres-binary,tracing] | 1.6.6 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12, python3.11, python3.13 |
| paquet Python | ladybug | 0.19.0 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12, python3.11, python3.13 |
| paquet Python | gunicorn | 23.0.0 | MIT | interpréteurs, par ordre de préférence python3.12, python3.11, python3.13 |
| paquet Python | uvicorn | 0.53.0 | BSD-3-Clause | interpréteurs, par ordre de préférence python3.12, python3.11, python3.13 |
| paquet Python | fastapi | 0.141.1 | MIT | interpréteurs, par ordre de préférence python3.12, python3.11, python3.13 |
| paquet Python | fastapi-users | 15.0.5 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12, python3.11, python3.13 |
| paquet Python | litellm | 1.105.0 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12, python3.11, python3.13 |
| paquet Python | openai | 2.54.0 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12, python3.11, python3.13 |
| paquet Python | sqlalchemy | 2.0.54 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12, python3.11, python3.13 |
| paquet Python | alembic | 1.20.0 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12, python3.11, python3.13 |
| paquet Python | asyncpg | 0.31.0 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12, python3.11, python3.13 |
| paquet Python | psycopg2-binary | 2.9.13 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12, python3.11, python3.13 |
| paquet Python | pgvector | 0.3.6 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12, python3.11, python3.13 |
| paquet Python | opentelemetry-sdk | 1.44.0 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12, python3.11, python3.13 |
| paquet Python | opentelemetry-exporter-otlp-proto-http | 1.44.0 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12, python3.11, python3.13 |
| paquet Python | langdetect | 1.0.9 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12, python3.11, python3.13 |
| paquet Python | pixeltable-pgserver | 0.7.1 | Apache-2.0 | interpréteurs, par ordre de préférence python3.12, python3.11, python3.13 |
Les images sont épinglées par étiquette dans le descripteur, et par condensé (digest) quand le descripteur en déclare un (le bundle hors ligne refuse alors une image téléchargée qui ne le porte pas) ; le condensé est enregistré dans le miroir du Manager à l'import du bundle hors ligne, et chaque téléchargement ou chargement est vérifié par rapport à lui.
Systèmes et architectures pris en charge
| Méthode | Systèmes d'exploitation | Architectures |
|---|
python | famille RHEL (dnf), famille Debian (apt), Arch Linux (pacman) | x86_64, aarch64 (non restreintes par le descripteur) |
podman | famille RHEL (dnf), famille Debian (apt), Arch Linux (pacman) | x86_64, aarch64 (non restreintes par le descripteur) |
Systèmes hôtes certifiés : RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). Le contrôle préalable des hôtes accepte ces systèmes (une autre version d'une famille connue donne un avertissement, une version en fin de vie est refusée) et les architectures x86_64 et aarch64.
Prérequis
Hôte
- au moins 4096 Mo de mémoire (bloquant,
memory).
- au moins 8192 Mo de mémoire (avertissement,
memory_comfort).
- au moins 2 CPU (bloquant,
cpu).
- au moins 10240 Mo libres pour
/var/lib/navin (bloquant, disk).
Réseau et ports
| Composant | Nom du port | Port | Ouvert dans le pare-feu de l'hôte |
|---|
api | api | 8420/tcp | oui |
api | api_local | 8420/tcp | non |
ui | ui | 8421/tcp | oui |
mcp | mcp | 8422/tcp | non |
Services et connexions nécessaires
Détail et résolution : voir Dépendances.
Méthodes et modes d'installation
| Méthode | Défaut | Ce que la méthode utilise |
|---|
python | oui | un environnement virtuel Python qui contient les paquets Python du descripteur |
podman | - | les images de conteneur du descripteur, exécutées par Podman sous systemd |
Composants
| Composant | Type | Méthodes d'installation | Ports |
|---|
API Cognee (api) | maître | python, podman | 8420/tcp, 8420/tcp |
Interface Cognee (ui) | maître | podman | 8421/tcp |
Serveur MCP Cognee (mcp) | maître | podman | 8422/tcp |
Serveur unique (single) (par défaut)
Une API (un processus gunicorn) propriétaire des fichiers LadybugDB de l'hôte, avec l'interface et le serveur MCP facultatifs à côté.
Ce que le mode déploie :
| Composant | Placement |
|---|
api | min 1, max 1 |
ui | min 1, max 1 |
mcp | min 1, max 1 |
Installer ce service
L'assistant d'installation du Navin Manager planifie, valide et exécute l'installation ; il faut la permission services:install sur le cluster.
-
Ouvrez l'assistant. Dans Clusters, choisissez l'action de ligne Installer des services du cluster cible. L'assistant s'ouvre sur sa première étape, Service.
-
Choisissez le service. À l'étape Service, sélectionnez Cognee. La carte affiche la licence Apache-2.0 et les dépendances dont l'installation a besoin. Choisissez la Méthode parmi python, podman (par défaut python).
-
Choisissez les hôtes et le mode. À l'étape Hôtes, cochez les hôtes, puis choisissez le Mode : single (par défaut). Chaque mode déploie les composants listés dans Méthodes et modes d'installation. Avec plusieurs composants, placez chacun sur ses hôtes dans Répartition des composants (Proposer un placement propose un placement qui respecte les cardinalités).
-
Liez les dépendances. À l'étape Liaisons, choisissez pour chaque dépendance (database, llm, otel) Installer avec la plateforme ou Utiliser une connexion existante ; une dépendance facultative peut rester sur Aucune liaison.
-
Configurez. À l'étape Configuration, relisez les paramètres (voir Paramètres de configuration). Les mots de passe laissés vides avec une valeur générée par défaut sont générés et scellés par le Manager.
-
Relisez et installez. À l'étape Installation, le Manager valide le plan et affiche l'ordre d'installation ; quand il indique « Le plan est valide. Prêt pour l'installation. », choisissez Installer. Un mode hautement disponible n'est installé que si ses contrôles HA réussissent.
-
Vérifiez. L'opération se termine quand les contrôles de santé de chaque instance réussissent (voir Contrôles de santé) ; le service apparaît alors en marche dans Services. Ouvrez le service et choisissez Lancer le test fonctionnel dans la carte Contrôles : Dans un jeu de données dédié (navin-smoke-<nonce>) : vérifie qu'un appel sans clé et une inscription publique sont refusés, ajoute deux textes, lance cognify (extraction du graphe par le LLM et plongements), retrouve un fragment par recherche sémantique, demande une complétion sur le graphe, lit le graphe du jeu de données, puis supprime le jeu de données quoi qu'il arrive.
Connecter un service existant
| |
|---|
| Schémas | https, http |
| Port par défaut | 8000 |
| Authentification | obligatoire |
| Contrôle de santé | /health |
| Méthode d'authentification | Champs | Description |
|---|
api_key | api_key | Clé d'API d'un utilisateur de Cognee (POST /api/v1/auth/api-keys), envoyée en X-Api-Key ; le serveur doit tourner avec REQUIRE_AUTHENTICATION et ENABLE_BACKEND_ACCESS_CONTROL à true. |
Documentation officielle : https://docs.cognee.ai/http_api
Haute disponibilité
Topologie par mode
| Modes | Niveau le plus haut du catalogue | Répartition | Composant du quorum | Domaines de panne | Description |
|---|
single | autonome (standalone) | unique (single) | - | 1 | Une API propriétaire des fichiers de graphe LadybugDB embarqués : sa perte arrête l'API de mémoire jusqu'à son redémarrage ou sa restauration ; les métadonnées relationnelles et les vecteurs restent dans PostgreSQL. |
Remarques
- Profil standard (PostgreSQL avec pgvector et LadybugDB embarqué) : instance unique uniquement. LadybugDB est un moteur embarqué dont les fichiers sont verrouillés par un seul processus (le point d'entrée officiel lance un seul processus gunicorn) ; deux API garderaient chacune un graphe différent. Aucun mode distribué ni répliqué n'est proposé.
- Les moteurs de graphe externes ne sont pas proposés : Neo4j, Neo4j Aura et Neptune sont exclus (licence ou service cloud), et le moteur de graphe PostgreSQL de Cognee 1.6.6 (postgres_demo) est une démonstration que le code source déclare non prête pour la production. Turso n'est pas un moteur validé de la plateforme.
- Avec le service PostgreSQL hautement disponible, un hôte perdu est remplacé par une réinstallation et la restauration de la dernière sauvegarde (base, fichiers LadybugDB et racine des données pris ensemble).
- L'API n'expose aucun point de métriques (pas de route Prometheus en 1.6.6) : l'observabilité utilise des sondes blackbox de /health et la vérification authentifiée du service ; les traces vont vers OpenTelemetry quand il est lié.
Paramètres de configuration
Réseau
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|
Port de l'API (port) | port | 8420 | min 1024 | non | non | oui | Port de l'API REST (8000 en amont, déplacé hors des ports de vLLM et des autres services). |
Exposition de l'API (listen_scope) | enum | network | network, local | non | non | oui | network : l'API écoute sur la seule adresse privée de l'hôte (jamais sur toutes les adresses) et le pare-feu de l'hôte l'ouvre aux consommateurs ; local : boucle locale uniquement, pour des consommateurs du même hôte. Elle n'est jamais publiée par une passerelle. |
TLS (tls_enabled) | bool | false | - | non | non | oui | Servir l'API en TLS (gunicorn --certfile et --keyfile) avec le certificat que le Manager émet pour l'hôte ; la liaison des consommateurs passe alors en https et le cookie d'authentification est sécurisé uniquement. |
Adresse publique de l'interface (public_url) | string | (vide) | ^(|https?://[A-Za-z0-9.-]+(:[0-9]{1,5})?)$ | non | non | oui | Adresse qu'ouvrent les utilisateurs pour l'interface derrière la passerelle, par exemple https://cognee.bank.internal : c'est la seule origine admise par les règles CORS de l'API (avec les identifiants) et, en https, le cookie d'authentification est sécurisé uniquement. Vide : l'adresse du port de l'interface de l'hôte. |
Délai des requêtes (request_timeout_s) | int | 3600 | min 60, max 86400, seconds | non | non | oui | Secondes qu'une requête peut durer avant que gunicorn redémarre le processus (--timeout) : un cognify synchrone d'un gros jeu de données est long. |
Modèles
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|
LLM (llm_model) | string | qwen-local | ^[A-Za-z0-9._:/@-]{1,128}$ | non | non | oui | Nom du modèle de la passerelle utilisé pour l'extraction du graphe (sortie structurée JSON), les résumés et les réponses ; par défaut qwen-local, le nom servi par défaut d'un moteur vLLM lié à LiteLLM (la passerelle n'a pas d'entrée par défaut, audit P5B-010). |
Jetons de réponse du LLM (llm_max_tokens) | int | 4096 | min 256, max 131072 | non | non | oui | Plus grande complétion d'un appel au LLM (LLM_MAX_COMPLETION_TOKENS, 16384 en amont) : la garder dans le contexte du modèle local. |
Modèle de plongement (embedding_model) | string | bge-m3 | ^[A-Za-z0-9._:/@-]{1,128}$ | non | non | oui | Nom du modèle de plongement de la passerelle (/v1/embeddings compatible OpenAI, sans paramètre dimensions) ; par défaut bge-m3, servi par un moteur vLLM en mode plongement lié à LiteLLM. |
Taille des vecteurs (embedding_dimensions) | int | 1024 | min 64, max 16000 | non | non | oui | Taille des vecteurs que renvoie le modèle de plongement (1024 pour bge-m3) : les colonnes vector des jeux de données sont créées avec elle. La changer demande de nouveaux jeux de données (ou une restauration dans une installation vide). |
Jetons d'entrée du plongement (embedding_max_tokens) | int | 8192 | min 128, max 131072 | non | non | oui | Jetons qu'accepte le modèle de plongement par entrée (EMBEDDING_MAX_COMPLETION_TOKENS, 8192 pour bge-m3) : les fragments y sont limités. Les comptes de jetons utilisent les encodages tiktoken embarqués : aucun tokenizer n'est téléchargé. |
Clé de la passerelle (llm_api_key) | password | (vide) | - | non | oui | non | Clé virtuelle LiteLLM de Cognee (sk-...), le moyen de mesurer et de plafonner ses dépenses ; vide, la clé maîtresse de la passerelle liée est utilisée. |
Limite de débit du LLM (llm_requests_per_minute) | int | 0 | min 0, max 100000 | non | non | oui | Appels au LLM et aux plongements par minute pour toute l'installation (LLM_RATE_LIMIT_* et EMBEDDING_RATE_LIMIT_*) ; 0 : pas de limite de Cognee, la passerelle applique toujours les limites de sa clé. |
Traitement et limites
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|
Taille des fragments (chunk_size) | int | 1500 | min 100, max 32000 | non | non | oui | Taille par défaut des fragments en lesquels cognify découpe les documents (CHUNK_SIZE, en jetons ; une requête peut donner son propre chunk_size). |
Recouvrement des fragments (chunk_overlap) | int | 10 | min 0, max 2000 | non | non | oui | Jetons répétés entre deux fragments consécutifs (CHUNK_OVERLAP). |
Traitements simultanés (max_concurrent_pipelines) | int | 2 | min 1, max 64 | non | non | oui | Jeux de données traités en même temps par la file des jeux de données (DATASET_QUEUE_MAX_CONCURRENT) ; les autres attendent. cognify consomme beaucoup de processeur et de mémoire (analyse, découpage, fusion du graphe dans le processus LadybugDB embarqué) : ne l'augmenter qu'avec la mémoire correspondante. (recommandé clamp(floor(host.cpu_count / 4), 1, 16)) |
Cache du graphe (graph_buffer_pool_mb) | int | 512 | min 64, max 65536, MB | non | non | oui | Cache de chaque graphe LadybugDB ouvert (KUZU_BUFFER_POOL_SIZE) : la mémoire réservée par graphe de jeu de données lu ou écrit. |
Retour automatique (auto_feedback) | bool | false | - | non | non | oui | Analyser chaque recherche répondue d'une session par un appel structuré de plus au LLM pour garder des consignes dans la session (AUTO_FEEDBACK, actif en amont) ; désactivé par défaut pour diviser par deux le coût LLM des recherches. |
Clés d'API par utilisateur (max_api_keys_per_user) | int | 10 | min 1, max 100 | non | non | oui | Quota de clés d'API qu'un utilisateur peut créer (MAX_USER_API_KEYS). |
Stockage et rétention
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|
Rétention des sessions (session_ttl_days) | int | 7 | min 1, max 3650, days | non | non | oui | Jours pendant lesquels l'historique des questions et réponses d'une session de recherche est gardé dans le cache des sessions (SESSION_TTL_SECONDS) ; les jeux de données, graphes et vecteurs sont gardés jusqu'à leur suppression par l'API. |
Interface et MCP
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|
Interface web (ui_enabled) | bool | false | - | non | non | oui | Lancer l'interface officielle (cognee-ui, Next.js, méthode podman uniquement) à côté de l'API : connexion avec le compte de l'administrateur, jeux de données, explorateur du graphe et recherches. Le navigateur appelle directement l'API, qui doit donc être joignable par les utilisateurs (listen_scope network). |
Port de l'interface (ui_port) | port | 8421 | min 1024 | non | non | oui | Port de l'interface (HTTP simple : la publier par la passerelle TLS de la plateforme). |
Serveur MCP (mcp_enabled) | bool | false | - | non | non | oui | Lancer le serveur MCP officiel (cognee-mcp, méthode podman uniquement) en mode API avec la clé d'API de service : outils remember, recall, search et cognify pour les agents du même hôte. Il n'a pas d'authentification propre, il n'écoute donc que sur la boucle locale de l'hôte. |
Port MCP (mcp_port) | port | 8422 | min 1024 | non | non | oui | Port du point d'accès HTTP streamable /mcp du serveur MCP, 127.0.0.1 de l'hôte uniquement. |
Sécurité
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|
Courriel de l'administrateur (admin_email) | string | cognee-admin@navin.internal | ^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$ | non | non | non | Identifiant de l'utilisateur par défaut de Cognee (DEFAULT_USER_EMAIL, superutilisateur, détenteur de la clé d'API de service) ; le compte default_user@example.com du code amont n'est jamais créé. |
Mot de passe administrateur (admin_password) | password | généré | - | non | oui | non | Mot de passe de l'utilisateur par défaut (DEFAULT_USER_PASSWORD), généré à chaque installation : Cognee l'applique une fois, à un compte sans mot de passe ; ensuite il se change dans Cognee uniquement (rotation par l'administrateur). |
Clé d'API de service (service_api_key) | password | généré | - | non | oui | non | Clé d'API de l'utilisateur par défaut installée par le lanceur à chaque démarrage (en-tête X-Api-Key, stockée sous forme d'empreinte), donnée aux consommateurs comme secret api_key du point d'accès api et utilisée par le serveur MCP et le test fonctionnel ; renouvelée par une nouvelle valeur et un redémarrage. |
Secret JWT (jwt_secret) | password | généré | - | non | oui | non | FASTAPI_USERS_JWT_SECRET qui signe les jetons et cookies de connexion ; le changer ferme toutes les sessions. |
Secret de réinitialisation (reset_password_secret) | password | généré | - | non | oui | non | FASTAPI_USERS_RESET_PASSWORD_TOKEN_SECRET des jetons de réinitialisation du mot de passe. |
Secret de vérification (verification_secret) | password | généré | - | non | oui | non | FASTAPI_USERS_VERIFICATION_TOKEN_SECRET des jetons de vérification des courriels. |
Sel des clés d'API (api_key_salt) | password | généré | - | non | oui | non | API_KEY_HASH_SALT des clés d'API stockées (HASH_API_KEY actif) ; le changer invalide toutes les clés d'API sauf celle de service, que le lanceur réinstalle. |
Durée de connexion (token_lifetime_minutes) | int | 60 | min 5, max 1440, minutes | non | non | oui | Durée de vie d'un jeton ou d'un cookie de connexion (JWT_LIFETIME_SECONDS). |
Inscription libre (allow_registration) | bool | false | - | non | non | oui | Permettre à quiconque atteint l'API de créer un compte (POST /api/v1/auth/register, ouvert en amont). Désactivé : le lanceur répond 403 sauf si la requête porte la clé d'API de service, les comptes sont donc créés par l'administrateur ou par Navin Enterprise. |
Ingestion par URL (allow_url_ingestion) | bool | false | - | non | non | oui | Permettre à add de récupérer des pages web et de cloner des dépôts donnés par URL (ALLOW_HTTP_REQUESTS ; les adresses privées restent refusées par la protection SSRF de Cognee). Désactivé : uniquement des fichiers téléversés et des textes. |
Requêtes Cypher (allow_cypher) | bool | false | - | non | non | oui | Autoriser le type de recherche CYPHER (requêtes brutes sur le graphe, ALLOW_CYPHER_QUERY, désactivé en amont). |
Observabilité
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|
Niveau de journalisation (log_level) | enum | WARNING | ERROR, WARNING, INFO, DEBUG | non | non | non | Verbosité de Cognee et de gunicorn (LOG_LEVEL). |
Traçage (tracing_enabled) | bool | false | - | non | non | oui | Exporter les spans OpenTelemetry de Cognee (COGNEE_TRACING_ENABLED) vers le collecteur OpenTelemetry lié (OTLP sur HTTP, méthode python uniquement). |
Dépendances
Pour chaque dépendance active, le Manager prend la première solution parmi : la liaison choisie dans l'assistant ; un service de la même installation qui la fournit ; un service déjà installé dans le cluster ; la seule connexion du type attendu. Sinon, une dépendance facultative reste non liée, et une dépendance obligatoire est ajoutée à l'installation dans son mode par défaut (la colonne ci-dessous nomme le service du catalogue ajouté).
| Liaison | Fournie par | Type de connexion | Point d'accès | Facultative | Quand rien n'est lié | Description |
|---|
database | postgresql (versions >= 14) | postgresql | sql | non | postgresql est ajouté à l'installation | Base dédiée cognee : utilisateurs, jeux de données, permissions et état des traitements (migrations alembic) et les collections pgvector de chaque jeu de données dans son propre schéma ds_<jeu> de la même base. Le provisionnement crée le rôle cognee, propriétaire de cette seule base (ni superutilisateur, ni CREATEDB), et l'extension vector. |
llm | litellm | - | api | non | litellm est ajouté à l'installation | Passerelle compatible OpenAI du LLM (extraction du graphe, résumés, réponses) et du modèle de plongement ; les moteurs vLLM et Ollama du Manager sont joints à travers elle. Le lanceur refuse de démarrer quand la passerelle ne liste pas les deux modèles. |
otel | otel-collector | - | otlp_http | oui | reste non liée (facultative) | Traces OpenTelemetry des traitements et des recherches (OTLP sur HTTP, méthode python uniquement : l'image officielle n'a pas le SDK OpenTelemetry). |
Vérifications des points d'accès liés
- le point d'accès
/v1/models de la liaison llm répond avec le statut 200 et liste les valeurs de llm_model, embedding_model, vérifié par le Manager avant l'installation (bloquant, llm_models).
Points d'accès
| Point d'accès | Schéma | Composant | Port | Chemin | Paramètre TLS | Paramètres de liaison | Secrets de liaison | Commande de provisionnement |
|---|
api | http | api | 8420 (port) | /api/v1 | tls_enabled | admin_email, graph_backend, vector_backend, access_control, embedding_dimensions | api_key | - |
Fichiers de configuration client
Fichiers rendus pour le téléchargement de la configuration client :
cognee.env (client.env.j2)
Commandes
| Commande | Composant | Cible | Description |
|---|
Santé détaillée (health_detailed) | api | premier hôte | Santé de chaque stockage et de la passerelle de modèles telle que l'API la voit (GET /health/detailed : relationnel, vecteurs, graphe, fichiers, LLM et plongement). |
Appliquer les migrations (migrate) | api | premier hôte | Applique les migrations relationnelles (alembic) et les révisions du graphe et des vecteurs de la version (cognee-cli upgrade, fait aussi à chaque démarrage de l'API). Méthode python ; avec podman l'API les applique à son démarrage. |
Journaux récents (logs) | api | hôte choisi | Dernières lignes du journal de l'API. |
Journaux de l'interface (ui_logs) | ui | hôte choisi | Dernières lignes du journal de l'interface. |
Journaux MCP (mcp_logs) | mcp | hôte choisi | Dernières lignes du journal du serveur MCP. |
Contrôles de santé
Vivacité (par instance)
| Composant | Contrôle | Détails |
|---|
api | HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn if config.tls_enabled and config.listen_scope == 'network' else ((host.ip or '127.0.0.1') if config.listen_scope == 'network' else '127.0.0.1') }}:{{ config.port }}/health | Attendu 200 ; Attendu "status":"ready" ; 120 tentatives ; intervalle 3 s ; délai 10 s |
ui | HTTP http://{{ host.ip or '127.0.0.1' }}:{{ config.ui_port }}/api/runtime-config | Attendu 200 ; 60 tentatives ; intervalle 2 s ; délai 5 s |
mcp | TCP 127.0.0.1:{{ config.mcp_port }} | 60 tentatives ; intervalle 2 s ; délai 5 s |
Disponibilité (contrôle du service)
| Contrôle | Détails |
|---|
{{ (paths.opt ~ '/venv/bin/python') if service.method == 'python' else '/usr/bin/python3' }} {{ paths.opt }}/app/navin_cognee.py check {{ paths.etc }}/api.env {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn if config.tls_enabled and config.listen_scope == 'network' else ((host.ip or '127.0.0.1') if config.listen_scope == 'network' else '127.0.0.1') }}:{{ config.port }}/api/v1/datasets {{ tls.ca_file if config.tls_enabled else '' }} | 10 tentatives ; intervalle 3 s ; délai 15 s |
Test fonctionnel
Dans un jeu de données dédié (navin-smoke-<nonce>) : vérifie qu'un appel sans clé et une inscription publique sont refusés, ajoute deux textes, lance cognify (extraction du graphe par le LLM et plongements), retrouve un fragment par recherche sémantique, demande une complétion sur le graphe, lit le graphe du jeu de données, puis supprime le jeu de données quoi qu'il arrive. (api: refused_without_key, no_anonymous_account, add, cognify, semantic_search, graph_completion, graph, cleanup)
Contrôles préalables
| Contrôle | Type | Signification | Sévérité | Composants |
|---|
memory | memory_mb {"min": 4096} | au moins 4096 Mo de mémoire | bloquant | api |
memory_comfort | memory_mb {"min": 8192} | au moins 8192 Mo de mémoire | avertissement | api |
cpu | cpu_count {"min": 2} | au moins 2 CPU | bloquant | api |
disk | disk_free_mb {"min": 10240} | au moins 10240 Mo libres pour /var/lib/navin | bloquant | api |
api_port_free | port_free {"param": "port"} | port 8420 libre sur l'hôte | bloquant | api |
ui_port_free | port_free {"param": "ui_port"} | port 8421 libre sur l'hôte, seulement quand ui_enabled est vrai | bloquant | ui |
mcp_port_free | port_free {"param": "mcp_port"} | port 8422 libre sur l'hôte, seulement quand mcp_enabled est vrai | bloquant | mcp |
llm_models | http_reachable {"binding": "llm", "path": "/v1/models", "bearer_secret": "token", "contains_params": ["llm_model", "embedding_model"], "timeout_s": 10} | le point d'accès /v1/models de la liaison llm répond avec le statut 200 et liste les valeurs de llm_model, embedding_model, vérifié par le Manager avant l'installation | bloquant | api |
Sauvegarde et restauration
L'API est d'abord arrêtée (son arrêt écrit le journal de chaque fichier LadybugDB), puis pg_dump (format custom, sans propriétaire ni privilège) de la base dédiée (métadonnées relationnelles et schéma pgvector de chaque jeu de données) et archives tar de la racine système (fichiers de graphe LadybugDB, cache des sessions) et de la racine des données (documents stockés), avec un manifeste de leurs sha256 ; l'API est relancée. La vérification contrôle chaque sha256, lit la table des matières de la sauvegarde et chaque membre des deux archives. Restauration, API arrêtée : en une transaction DROP OWNED BY le rôle de Cognee et les objets de la sauvegarde (l'extension vector reste celle du provisionnement), puis les deux racines sont remplacées.
| |
|---|
| Format | cognee-pgdump-ladybug |
| Composant | api |
| Fichiers | {{ backup.dir }}/cognee.dump, {{ backup.dir }}/system.tar.gz, {{ backup.dir }}/data.tar.gz, {{ backup.dir }}/manifest.json |
| Test de restauration | oui |
| Instances arrêtées pendant la restauration | oui |
Mise à niveau
| |
|---|
| Prise en charge depuis | |
| Avec état | oui |
| Sauvegarde avant la mise à niveau | oui |
| Retour arrière | non (Les migrations de Cognee (alembic et les révisions du format de stockage LadybugDB) ne vont qu'en avant et le Manager ne les annule jamais : le retour arrière est la restauration de la sauvegarde prise avant la mise à jour.) |
Désinstallation
Chemins supprimés quand les données sont purgées : {{ paths.data }}, {{ paths.log }}.
Liens rapides
- Référence de l'API :
{{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.port }}/docs
- Interface Cognee :
{{ (config.public_url ~ '/dashboard') if config.public_url else ('http://' ~ host.fqdn ~ ':' ~ config.ui_port ~ '/dashboard') }}
Documentation amont