Préparer l'environnement et la clé d'API

À la fin de cette leçon, vous aurez un environnement Python capable d'appeler un grand modèle, et un script de vérification qui le confirme. Le tout prend environ une demi-heure, dont la plus grande partie pour créer un compte.

Installer Python et uv

Ce cours gère l'environnement Python avec uv. C'est un gestionnaire de paquets Python bien plus rapide que le duo traditionnel pip + venv, et il installe au passage une version adaptée de Python : inutile d'installer Python séparément d'abord.

Sous macOS et Linux, dans un terminal :

curl -LsSf https://astral.sh/uv/install.sh | sh

Sous Windows, dans PowerShell :

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Avec Homebrew, brew install uv fonctionne aussi. Une fois l'installation terminée, ouvrez une nouvelle fenêtre de terminal et lancez uv --version ; si un numéro de version s'affiche, c'est installé.

Si vous êtes habitué à pip et venv, ou à conda, vous pouvez tout à fait continuer. Le code de ce cours ne dépend que de quelques paquets courants, n'importe quel outil fera l'affaire. Pour les commandes ci-dessous, je donne aussi la version pip.

Créer un projet

Choisissez un endroit pour votre code et créez un dossier de projet :

uv init --no-package ai-course
cd ai-course
uv add openai

--no-package signifie « ce projet sert seulement à ranger des scripts, il n'est pas destiné à être empaqueté et publié ». Sans ce paramètre, les versions récentes de uv génèrent une structure pour l'empaquetage (un dossier src/ et une configuration de build), superflue pour ce cours.

uv init a créé ces fichiers :

ai-course/
  .git/             uv 顺手帮你初始化了 git 仓库
  .gitignore        已经写好了该忽略的文件，包括 .venv
  .python-version   这个项目用哪个版本的 Python
  main.py           一个打印 Hello 的示例脚本
  pyproject.toml    项目信息和依赖列表
  README.md

uv add openai ajoute encore deux choses : le dossier .venv est l'environnement virtuel du projet, dans lequel openai est installé ; uv.lock enregistre la version exacte de chaque paquet, si bien que quelqu'un qui récupère votre projet et lance uv sync obtient exactement le même environnement. En même temps, openai est ajouté aux dependencies de pyproject.toml.

Vérifions que ça s'exécute :

uv run main.py

Si vous voyez Hello from ai-course!, c'est bon.

Désormais, pour exécuter les scripts de ce projet, utilisez uv run :

uv run python 你的脚本.py

uv run utilise automatiquement l'environnement virtuel du projet ; inutile de l'activer à la main.

Avec pip, cela donne ceci, pour le même résultat :

mkdir ai-course && cd ai-course
python3 -m venv .venv
source .venv/bin/activate      # Windows 用 .venv\Scripts\activate
pip install openai

Avec cette méthode, il faut relancer source .venv/bin/activate à chaque nouveau terminal, puis exécuter directement python votre_script.py.

Pourquoi un environnement virtuel

Chaque projet a son propre jeu de paquets, sans interférence. Si vous installez aujourd'hui la dernière version d'openai pour ce cours et qu'un vieux projet a besoin d'une ancienne version demain, les deux fonctionnent. Si vous installez tous les paquets dans le Python du système, vous finirez tôt ou tard par avoir des conflits de versions difficiles à démêler.

Éditeur

Prenez l'éditeur qui vous convient. Sans préférence, je recommande VS Code avec l'extension Python officielle de Microsoft. Après avoir ouvert le dossier ai-course dans VS Code, appuyez sur Ctrl+Shift+P (Cmd+Shift+P sous macOS), tapez « Python: Select Interpreter » et choisissez le Python qui se trouve dans .venv. Sinon l'éditeur ne reconnaît pas les paquets installés et souligne tout en rouge.

Obtenir une clé d'API DeepSeek

1. Ouvrez la plateforme ouverte DeepSeek, inscrivez-vous et connectez-vous (l'inscription se fait par numéro de téléphone).
2. Dans le menu de gauche, allez dans « Recharge » (充值) et ajoutez un peu d'argent. La première partie coûte en général moins d'un dollar ; le montant minimum suffit.
3. Allez sur la page API keys, cliquez sur « Créer une clé API » et donnez-lui un nom, par exemple « ai-course ».
4. Copiez la clé générée. Elle commence par sk- et ne s'affiche qu'une seule fois : une fois la page fermée, vous ne la reverrez plus. Si vous ne l'avez pas copiée, supprimez-la et créez-en une nouvelle.

Définir la clé comme variable d'environnement

Une clé, c'est l'argent de votre compte. Quiconque l'obtient peut appeler des modèles avec votre solde. D'où une règle : n'écrivez jamais une clé dans un fichier de code.

Quel est le problème ? Le code est commité dans git, poussé sur GitHub, partagé avec des collègues, collé sur le web pour poser une question. À chaque étape, la clé peut s'échapper. Des gens scannent en permanence les dépôts publics de GitHub à la recherche de clés ; une clé divulguée est très vite volée.

La bonne méthode est de mettre la clé dans une variable d'environnement, que le code lit à l'exécution. Ce cours utilise trois variables d'environnement :

Si nous n'utilisons pas le nom DEEPSEEK_API_KEY de la documentation officielle de DeepSeek, c'est parce que le code de ce cours doit pouvoir passer d'un fournisseur à l'autre. Pour changer de fournisseur plus tard, il suffit de modifier la valeur de ces trois variables, sans toucher une ligne de code.

macOS et Linux : ouvrez ~/.zshrc (zsh est le shell par défaut de macOS) ou ~/.bashrc (la plupart des Linux) et ajoutez à la fin :

export LLM_API_KEY="sk-你的密钥"
export LLM_BASE_URL="https://api.deepseek.com"
export LLM_MODEL="deepseek-flash"

Enregistrez, puis fermez et rouvrez le terminal, ou lancez source ~/.zshrc.

Windows : dans PowerShell, lancez les trois lignes ci-dessous ; elles enregistrent les variables de façon permanente dans votre compte utilisateur :

setx LLM_API_KEY "sk-你的密钥"
setx LLM_BASE_URL "https://api.deepseek.com"
setx LLM_MODEL "deepseek-flash"

Les variables définies par setx ne s'appliquent pas à la fenêtre courante : fermez PowerShell et rouvrez-le. C'est le piège le plus courant sous Windows : la variable est bien définie, mais le programme dit ne pas la trouver.

Autre méthode : le fichier .env

Certains préfèrent écrire la clé dans un fichier .env du dossier du projet et la charger au démarrage avec le paquet python-dotenv. C'est possible aussi, mais ajoutez d'abord .env à .gitignore :

echo ".env" >> .gitignore

D'abord .gitignore, ensuite .env. Dans l'ordre inverse, vous risquez de le commiter lors d'un git add .. Une fois commité, il reste dans l'historique de git même si vous le supprimez ensuite. Dans ce cas, n'essayez pas de nettoyer l'historique : supprimez directement la clé sur la plateforme et créez-en une nouvelle.

Vérifier

Enregistrez le script ci-dessous sous check_env.py :

"""检查三个环境变量有没有设置好，并用一次最便宜的请求确认密钥可用。"""
import os
import sys

from openai import APIConnectionError, AuthenticationError, OpenAI

key = os.environ.get("LLM_API_KEY")
base_url = os.environ.get("LLM_BASE_URL", "https://api.deepseek.com")
model = os.environ.get("LLM_MODEL", "deepseek-flash")

if not key:
    sys.exit("没有找到 LLM_API_KEY。设置完环境变量后，要重新打开一个终端窗口才会生效。")

# 只显示密钥的开头和结尾，避免截图时泄露
print(f"密钥：{key[:5]}...{key[-4:]}")
print(f"地址：{base_url}")
print(f"模型：{model}")

client = OpenAI(api_key=key, base_url=base_url)
try:
    available = [m.id for m in client.models.list().data]
except AuthenticationError:
    sys.exit("密钥不对（401）。检查有没有复制完整、有没有多出空格。")
except APIConnectionError:
    sys.exit("连不上服务器。检查地址有没有写错，或者网络是否需要代理。")

print(f"这个密钥能用的模型：{', '.join(available)}")
if model not in available:
    print(f"注意：{model} 不在列表里，调用时可能会报错或被映射到别的模型。")
else:
    print("一切正常，可以开始上课了。")

Exécution :

uv run python check_env.py

Voici ce que j'obtiens (le milieu de la clé est masqué) :

密钥：sk-7f...805f
地址：https://api.deepseek.com
模型：deepseek-flash
这个密钥能用的模型：deepseek-flash, deepseek-v4-pro
一切正常，可以开始上课了。

Si la dernière ligne affiche « tout est en ordre » (一切正常), l'environnement est prêt. L'avant-dernière ligne liste les modèles que votre clé peut appeler ; en septembre 2026, DeepSeek propose deepseek-flash et deepseek-v4-pro. Ce cours utilise par défaut deepseek-flash : bon marché, rapide, et capable de toutes les tâches du cours.

Ce script appelle l'interface « lister les modèles », qui ne génère aucun texte et ne coûte donc rien.

Passer à un autre fournisseur

Le code de ce cours ne dépend que du SDK Python d'OpenAI ; tout service compatible avec l'interface d'OpenAI fonctionne. Les fournisseurs ci-dessous ont une documentation en chinois ; adresses et noms de modèles d'après leur documentation officielle (septembre 2026) :

Deux points d'attention.

Premièrement, la « compatibilité avec l'interface d'OpenAI » varie d'un fournisseur à l'autre. Les appels de conversation de base fonctionnent partout, mais pour l'appel d'outils, la sortie JSON ou le streaming, certains modèles ne les prennent pas en charge et d'autres diffèrent dans les détails. Quand les leçons suivantes utiliseront ces fonctions, je signalerai ce qui est propre à DeepSeek.

Deuxièmement, Ollama en local est entièrement gratuit et fonctionne sans réseau, mais les modèles qui tournent sur un portable ordinaire sont petits et nettement moins bons que les grands modèles dans le cloud ; certains exercices risquent de ne pas aboutir. Je conseille de terminer d'abord la première partie avec un modèle dans le cloud ; le module 10 est consacré au déploiement local.

Problèmes courants

Le script affiche ModuleNotFoundError: No module named 'openai' : le paquet est installé dans l'environnement virtuel du projet, mais vous exécutez le Python du système. Lancez avec uv run python ..., ou activez d'abord l'environnement virtuel.

« LLM_API_KEY introuvable », alors que je l'ai définie : après avoir défini une variable d'environnement, il faut rouvrir le terminal. Si vous exécutez depuis VS Code, fermez et rouvrez tout VS Code ; fermer seulement le panneau du terminal ne suffit pas.

Erreur 401 : la clé a été copiée incomplètement, ou avec des espaces ou des guillemets en trop. Il se peut aussi que la clé ait été supprimée sur la plateforme.

Erreur 402 ou solde insuffisant : rechargez votre compte sur la plateforme.

Exercices

1. Dans le terminal, lancez echo $LLM_MODEL (dans PowerShell sous Windows, echo $env:LLM_MODEL) et vérifiez que le nom du modèle s'affiche.
2. Changez volontairement une lettre de LLM_API_KEY et relancez check_env.py pour voir à quoi ressemble l'erreur. Pensez à remettre la bonne valeur ensuite. Pour modifier temporairement une variable dans le terminal, vous pouvez écrire LLM_API_KEY=sk-wrong uv run python check_env.py : cela ne vaut que pour cette commande.
3. Si vous avez un compte Qwen ou Kimi, remplacez les trois variables par les valeurs de ce fournisseur d'après le tableau ci-dessus, et relancez check_env.py.

Auto-test

1. Pourquoi ne faut-il pas écrire la clé d'API directement dans le code ?

Le code est commité dans git, poussé sur GitHub, envoyé à d'autres. À chaque étape, la clé peut fuiter, et quiconque l'obtient peut dépenser directement l'argent de votre compte. Dans une variable d'environnement, le fichier de code ne contient aucun secret et peut être partagé sans risque.

2. Sous Windows, vous avez défini LLM_API_KEY avec setx et lancez aussitôt le script, qui dit ne pas la trouver. Pourquoi ?

setx a écrit la variable dans la configuration de l'utilisateur, mais les fenêtres déjà ouvertes ne relisent pas cette configuration. Fermez PowerShell (ou tout VS Code) et rouvrez-le.

3. Pourquoi ce cours utilise-t-il les trois variables LLM_API_KEY, LLM_BASE_URL et LLM_MODEL plutôt que DEEPSEEK_API_KEY ?

Pour pouvoir changer de fournisseur sans modifier le code. Tout service compatible avec l'interface d'OpenAI n'a besoin que de ces trois choses : une clé, une adresse, un nom de modèle. Changer de fournisseur revient à modifier la valeur de ces trois variables.