Kit de Démarrage Data Scientist

Ce guide couvre les workflows de machine learning et d'IA disponibles sur AKKO : notebooks, suivi d'expériences, inférence LLM locale, pipelines RAG et publication de rapports.

---

Environnement JupyterHub

AKKO fournit un environnement de notebooks complet avec plusieurs kernels de langage et options d'IDE.

Kernels Disponibles

Kernel	Version	Bibliothèques Clés
Python 3	3.11+	pandas, scikit-learn, pyspark, trino, langchain, matplotlib, seaborn
R	4.x	tidyverse, ggplot2, DBI
Julia	1.x	DataFrames, Plots

Options d'IDE

• JupyterLab -- interface de notebooks par défaut avec extensions
• code-server -- VS Code dans le navigateur (accessible depuis le lanceur JupyterHub)

Bibliothèques ML Pré-installées

# Machine Learning
import sklearn
import xgboost
import lightgbm

# Deep Learning
import torch

# Traitement de données
import pandas as pd
import polars as pl
from pyspark.sql import SparkSession

# Visualisation
import matplotlib.pyplot as plt
import seaborn as sns
import plotly.express as px

Connexion aux Données

# Spark Connect (tables Iceberg)
spark = SparkSession.builder.remote("sc://spark-connect:15002").getOrCreate()
df_spark = spark.sql("SELECT * FROM polaris.banking.transactions")

# Trino (SQL fédéré)
from trino.dbapi import connect
conn = connect(host="trino", port=8080, user="alice")

# PostgreSQL (direct)
import psycopg2
import os
conn = psycopg2.connect(
    host="postgresql-data",
    dbname="akko_data",
    user="akko",
    password=os.environ["POSTGRES_AKKO_PASSWORD"]
)

---

Suivi d'Expériences avec MLflow

MLflow suit les expériences, modèles et artefacts. Il est pré-configuré avec MinIO pour le stockage d'artefacts et PostgreSQL pour les métadonnées.

Journaliser une Expérience

import mlflow

mlflow.set_tracking_uri("http://mlflow:5000")
mlflow.set_experiment("credit-risk-model")

with mlflow.start_run(run_name="xgboost-v1"):
    # Journaliser les paramètres
    mlflow.log_param("n_estimators", 100)
    mlflow.log_param("max_depth", 6)
    mlflow.log_param("learning_rate", 0.1)

    # Entraîner le modèle
    import xgboost as xgb
    model = xgb.XGBClassifier(n_estimators=100, max_depth=6, learning_rate=0.1)
    model.fit(X_train, y_train)

    # Journaliser les métriques
    from sklearn.metrics import accuracy_score, f1_score
    y_pred = model.predict(X_test)
    mlflow.log_metric("accuracy", accuracy_score(y_test, y_pred))
    mlflow.log_metric("f1_score", f1_score(y_test, y_pred))

    # Journaliser le modèle
    mlflow.xgboost.log_model(model, "model")

Registre de Modèles

# Enregistrer un modèle
mlflow.register_model("runs:/<run_id>/model", "credit-risk-model")

# Charger un modèle enregistré
model = mlflow.pyfunc.load_model("models:/credit-risk-model/Production")
predictions = model.predict(new_data)

Interface MLflow

Accédez à l'interface de suivi MLflow via https://mlflow.<domaine> pour comparer les expériences, visualiser les métriques et gérer le registre de modèles.

---

Inférence LLM Locale avec Ollama + LiteLLM

AKKO exécute des LLM localement avec Ollama, et LiteLLM comme passerelle API unifiée.

Modèles Disponibles

Modèle	Taille	Cas d'Usage
Qwen 2.5-Coder:7B	~4.7 Go	Génération de code, assistance SQL
Qwen 2.5:3B	~2 Go	Génération de texte général
nomic-embed-text	~274 Mo	Embeddings de texte (RAG)

Utiliser LiteLLM (API Compatible OpenAI)

from openai import OpenAI

client = OpenAI(
    base_url="http://litellm:4000/v1",
    api_key="sk-akko"  # configuré dans LiteLLM
)

response = client.chat.completions.create(
    model="qwen2.5-coder:7b",
    messages=[
        {"role": "system", "content": "Tu es un assistant SQL utile."},
        {"role": "user", "content": "Écris une requête pour trouver les 10 meilleurs clients par revenu."}
    ]
)
print(response.choices[0].message.content)

Utiliser Ollama Directement

import requests
import os

response = requests.post(
    f"http://{os.environ['OLLAMA_HOST']}/api/generate",
    json={
        "model": "qwen2.5:3b",
        "prompt": "Explique ce qu'est Apache Iceberg en 3 phrases.",
        "stream": False
    }
)
print(response.json()["response"])

Intégration Jupyter AI

Jupyter AI est pré-installé. Utilisez la barre latérale de chat dans JupyterLab pour interagir avec les modèles locaux directement dans votre environnement de notebooks.

---

Pipeline RAG (pgvector + Ollama + LangChain)

AKKO inclut une pile complète de génération augmentée par récupération (RAG), fonctionnant entièrement sur site.

Architecture

Documents --> Embeddings (nomic-embed-text) --> pgvector (PostgreSQL)
                                                      |
Requête --> Embedding --> Recherche de similarité -----+
                                    |
                              Contexte + Requête --> Ollama (Qwen 2.5) --> Réponse

Construire un Pipeline RAG

from langchain_community.embeddings import OllamaEmbeddings
from langchain_community.vectorstores import PGVector
from langchain_community.llms import Ollama
from langchain.chains import RetrievalQA
from langchain.text_splitter import RecursiveCharacterTextSplitter
import os

# 1. Initialiser les embeddings
embeddings = OllamaEmbeddings(
    base_url=f"http://{os.environ['OLLAMA_HOST']}",
    model="nomic-embed-text"
)

# 2. Connecter à pgvector
CONNECTION_STRING = (
    f"postgresql://akko:{os.environ['POSTGRES_AKKO_PASSWORD']}"
    f"@postgresql-data:5432/akko_data"
)

vectorstore = PGVector(
    connection_string=CONNECTION_STRING,
    embedding_function=embeddings,
    collection_name="documents"
)

# 3. Ajouter des documents
from langchain.document_loaders import TextLoader
loader = TextLoader("rapport.txt")
documents = loader.load()
splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50)
chunks = splitter.split_documents(documents)
vectorstore.add_documents(chunks)

# 4. Interroger avec RAG
llm = Ollama(
    base_url=f"http://{os.environ['OLLAMA_HOST']}",
    model="qwen2.5:3b"
)

qa = RetrievalQA.from_chain_type(
    llm=llm,
    chain_type="stuff",
    retriever=vectorstore.as_retriever(search_kwargs={"k": 3})
)

result = qa.invoke("Quelles sont les conclusions principales du rapport ?")
print(result["result"])

Démo Pré-construite

Consultez shared/rag-pipeline-demo.ipynb dans JupyterHub pour un exemple complet fonctionnel.

---

Publication de Rapports avec Quarto

Quarto est pré-installé dans l'image notebook. Créez des rapports de qualité publication à partir de vos analyses.

Créer un Rapport

Créez un fichier .qmd dans JupyterLab :

---
title: "Analyse du Risque de Crédit"
author: "Équipe Data Science"
format:
  html:
    theme: cosmo
    toc: true
---

## Résumé

Ce rapport analyse les tendances du risque de crédit dans notre portefeuille.

```{python}
import pandas as pd
df = pd.read_sql("SELECT * FROM transactions", conn)
df.describe()

### Rendu

```bash
quarto render rapport.qmd

Publication sur AKKO Docs

Les rapports rendus sont publiés dans le volume published-reports, accessible via le service AKKO Docs à https://docs.<domaine>.

Consultez shared/04-akko-banking-report.qmd pour un exemple complet.