Entwicklungsumgebung und API-Schlüssel vorbereiten

Nach dieser Lektion hast du eine Python-Umgebung, die ein Sprachmodell aufrufen kann, und ein Prüfskript, das bestätigt, dass sie funktioniert. Das Ganze dauert etwa eine halbe Stunde, die meiste Zeit geht für die Registrierung eines Kontos drauf.

Python und uv installieren

Dieser Kurs verwaltet Python-Umgebungen mit uv. Das ist ein Paketmanager für Python, viel schneller als die klassische Kombination aus pip und venv, und er installiert nebenbei gleich eine passende Python-Version; du musst Python also nicht vorher separat installieren.

Unter macOS und Linux führst du im Terminal aus:

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

Unter Windows in der PowerShell:

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

Mit Homebrew geht auch brew install uv. Nach der Installation öffnest du ein neues Terminalfenster und führst uv --version aus; siehst du eine Versionsnummer, hat es geklappt.

Wenn du an pip und venv oder an conda gewöhnt bist, kannst du auch einfach dabei bleiben. Der Code dieses Kurses hängt nur von ein paar gängigen Paketen ab, und es ist egal, womit du sie installierst. Zu den Befehlen unten gebe ich jeweils auch die pip-Variante an.

Ein Projekt anlegen

Such dir einen Ort für deinen Code und leg ein Projektverzeichnis an:

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

--no-package heißt: „Das ist nur ein Projekt für Skripte, es soll nicht als Paket veröffentlicht werden.“ Ohne diese Option erzeugt neuere uv-Versionen eine Verzeichnisstruktur für Pakete (ein src/-Verzeichnis und Build-Konfiguration), die für diesen Kurs überflüssig ist.

uv init erzeugt diese Dateien:

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

uv add openai fügt zwei weitere hinzu: Das Verzeichnis .venv ist die virtuelle Umgebung dieses Projekts, und darin ist openai installiert; uv.lock hält die exakten Versionen aller Pakete fest, damit jemand anderes mit uv sync genau dieselbe Umgebung herstellen kann. Außerdem wird openai in die dependencies von pyproject.toml eingetragen.

Probier aus, ob es läuft:

uv run main.py

Siehst du Hello from ai-course!, stimmt alles.

Skripte in diesem Projekt führst du ab jetzt mit uv run aus:

uv run python 你的脚本.py

uv run nutzt automatisch die virtuelle Umgebung des Projekts; du musst sie nicht von Hand aktivieren.

Mit pip sieht es so aus, mit demselben Ergebnis:

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

Bei dieser Variante musst du in jedem neuen Terminal erneut source .venv/bin/activate ausführen und startest Skripte dann direkt mit python dein_skript.py.

Warum eine virtuelle Umgebung

Jedes Projekt bekommt seine eigenen Pakete, und sie kommen sich nicht in die Quere. Installierst du heute für diesen Kurs die neueste Version von openai und braucht morgen ein altes Projekt eine ältere Version, funktionieren trotzdem beide. Wenn du alle Pakete in das System-Python installierst, kommt es früher oder später zu Versionskonflikten, und die sind schwer aufzuräumen.

Editor

Nimm den Editor, mit dem du gut zurechtkommst. Wenn du keine Vorliebe hast, empfehle ich VS Code mit der offiziellen Python-Erweiterung von Microsoft. Nachdem du das Verzeichnis ai-course in VS Code geöffnet hast, drückst du Ctrl+Shift+P (unter macOS Cmd+Shift+P), tippst „Python: Select Interpreter“ und wählst das Python aus .venv. Nur dann erkennt der Editor deine installierten Pakete, und du hast nicht überall rote Wellenlinien.

Einen DeepSeek-API-Schlüssel besorgen

1. Öffne die DeepSeek-Entwicklerplattform, registriere dich mit deiner Handynummer und melde dich an.
2. Geh im Menü links auf „充值“ (Aufladen) und lade etwas Guthaben auf. Teil 1 kostet meist weniger als 1 US-Dollar, der Mindestbetrag reicht.
3. Klick auf der Seite API keys auf „创建 API key“ (API-Schlüssel erstellen) und gib ihm einen Namen, zum Beispiel „ai-course“.
4. Kopier den erzeugten Schlüssel. Er beginnt mit sk- und wird nur dieses eine Mal angezeigt; schließt du die Seite, siehst du ihn nie wieder. Hast du ihn nicht kopiert, löschst du ihn einfach und legst einen neuen an.

Den Schlüssel als Umgebungsvariable setzen

Ein Schlüssel ist so viel wert wie das Guthaben auf deinem Konto. Jeder, der ihn in die Hände bekommt, kann mit deinem Guthaben Modelle aufrufen. Daher gilt eine Regel: Ein Schlüssel kommt niemals in eine Code-Datei.

Was ist so schlimm daran? Code wird in Git committet, auf GitHub gepusht, mit Kollegen geteilt und ins Netz gestellt, um Fragen zu stellen. Bei jedem dieser Schritte kann der Schlüssel nach außen gelangen. Auf GitHub gibt es ständig Leute, die öffentliche Repositories gezielt nach Schlüsseln durchsuchen, und ein geleakter Schlüssel wird schnell missbraucht.

Richtig ist, den Schlüssel in eine Umgebungsvariable zu legen, die der Code zur Laufzeit ausliest. Dieser Kurs verwendet einheitlich drei Umgebungsvariablen:

Den Namen DEEPSEEK_API_KEY aus der offiziellen DeepSeek-Dokumentation verwenden wir nicht, weil der Code dieses Kurses zwischen verschiedenen Anbietern wechseln können soll. Wenn du später zu einem anderen Anbieter willst, änderst du nur die Werte dieser drei Variablen und keine einzige Zeile Code.

macOS und Linux: Öffne ~/.zshrc (die Standard-Shell von macOS ist zsh) oder ~/.bashrc (die meisten Linux-Systeme) und füg am Ende hinzu:

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

Speichern, das Terminal schließen und neu öffnen oder source ~/.zshrc ausführen.

Windows: Führ in der PowerShell die folgenden drei Zeilen aus; sie speichern die Variablen dauerhaft in deinem Benutzerkonto:

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

Mit setx gesetzte Variablen gelten nicht im aktuellen Fenster; du musst die PowerShell schließen und neu öffnen. Das ist die häufigste Falle unter Windows: Du hast die Variable doch gesetzt, und das Programm findet sie trotzdem nicht.

Eine andere Möglichkeit: die .env-Datei

Manche schreiben den Schlüssel lieber in eine .env-Datei im Projektverzeichnis und lesen sie beim Programmstart mit dem Paket python-dotenv ein. Das geht auch, aber trag .env unbedingt vorher in .gitignore ein:

echo ".env" >> .gitignore

Erst .gitignore ergänzen, dann .env anlegen. Machst du es umgekehrt, committest du sie vielleicht bei irgendeinem git add . mit. Und was einmal committet wurde, bleibt in der Git-Historie, auch wenn du es später löschst. Denk in diesem Fall nicht darüber nach, wie du die Historie bereinigst, sondern lösch den Schlüssel auf der Plattform und leg einen neuen an.

Prüfen

Speichere das folgende Skript als 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("一切正常，可以开始上课了。")

Ausführen:

uv run python check_env.py

Bei mir sieht das Ergebnis so aus (der mittlere Teil des Schlüssels ist ausgeblendet):

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

Steht in der letzten Zeile „一切正常“ (alles in Ordnung), ist die Umgebung fertig. Die vorletzte Zeile listet die Modelle, die dein Schlüssel aufrufen kann; stand September 2026 bietet DeepSeek deepseek-flash und deepseek-v4-pro an. Dieser Kurs nutzt standardmäßig deepseek-flash: günstig, schnell und für alle Aufgaben des Kurses gut genug.

Das Skript ruft die Schnittstelle „Modelle auflisten“ auf, die keinen Text erzeugt und daher nichts kostet.

Zu einem anderen Anbieter wechseln

Der Code dieses Kurses hängt nur vom Python-SDK von OpenAI ab; jeder Dienst mit OpenAI-kompatibler Schnittstelle funktioniert. Die folgenden Anbieter haben alle eine Dokumentation auf Chinesisch; für Adressen und Modellnamen gilt jeweils die offizielle Dokumentation (Stand September 2026):

Zwei Dinge sind zu beachten.

Erstens ist die „OpenAI-Kompatibilität“ nicht bei allen Anbietern gleich weit. Einfache Chat-Aufrufe funktionieren überall, aber Tool-Aufrufe, JSON-Ausgabe oder Streaming unterstützen manche Modelle nicht oder anders im Detail. Wenn spätere Lektionen diese Funktionen nutzen, sage ich dazu, was DeepSeek-spezifisch ist.

Zweitens ist ein lokales Ollama völlig kostenlos und braucht kein Internet, aber die Modelle, die auf einem normalen Laptop laufen, sind klein und deutlich schwächer als die großen Modelle in der Cloud; manche Übungen klappen damit vielleicht nicht. Arbeite Teil 1 am besten erst mit einem Cloud-Modell durch; Modul 10 widmet sich dem lokalen Betrieb.

Häufige Probleme

Beim Ausführen kommt ModuleNotFoundError: No module named 'openai': Das Paket ist in der virtuellen Umgebung des Projekts installiert, aber du führst das System-Python aus. Nutze uv run python ... oder aktiviere zuerst die virtuelle Umgebung.

„没有找到 LLM_API_KEY“ (LLM_API_KEY nicht gefunden), obwohl ich sie gesetzt habe: Nach dem Setzen einer Umgebungsvariable musst du das Terminal neu öffnen. Wenn du in VS Code arbeitest, musst du VS Code ganz schließen und neu starten; nur das Terminal-Panel darin zu schließen, reicht nicht.

Fehler 401: Der Schlüssel wurde unvollständig kopiert oder hat zusätzliche Leerzeichen oder Anführungszeichen. Oder der Schlüssel wurde auf der Plattform gelöscht.

Fehler 402 oder Hinweis auf zu wenig Guthaben: Guthaben auf der Plattform aufladen.

Übungen

1. Führ im Terminal echo $LLM_MODEL aus (in der Windows-PowerShell echo $env:LLM_MODEL) und prüf, dass der Modellname ausgegeben wird.
2. Ändere absichtlich einen Buchstaben von LLM_API_KEY und führ check_env.py aus. Wie sieht die Fehlermeldung aus? Danach wieder zurückändern. Eine Variable nur vorübergehend im Terminal zu ändern, geht so: LLM_API_KEY=sk-wrong uv run python check_env.py; das gilt nur für diesen einen Befehl.
3. Wenn du ein Konto bei Qwen oder Kimi hast, setz die drei Variablen laut Tabelle oben auf deren Werte und führ check_env.py noch einmal aus.

Selbsttest

1. Warum darf ein API-Schlüssel nicht direkt im Code stehen?

Code wird in Git committet, auf GitHub gepusht und an andere weitergegeben. Bei jedem dieser Schritte kann der Schlüssel durchsickern, und wer ihn hat, kann direkt das Guthaben auf deinem Konto verbrauchen. Liegt er in einer Umgebungsvariable, enthält die Code-Datei selbst kein Geheimnis und kann unbesorgt geteilt werden.

2. Unter Windows hast du LLM_API_KEY mit setx gesetzt und das Skript sofort ausgeführt, aber es findet die Variable nicht. Warum?

setx schreibt die Variable in die Benutzerkonfiguration, aber bereits geöffnete Fenster lesen die Konfiguration nicht neu ein. Schließ die PowerShell (oder ganz VS Code) und öffne sie neu.

3. Warum nutzt dieser Kurs die drei Variablen LLM_API_KEY, LLM_BASE_URL und LLM_MODEL statt DEEPSEEK_API_KEY?

Damit man beim Anbieterwechsel keinen Code ändern muss. Jeder OpenAI-kompatible Dienst braucht nur diese drei Dinge: Schlüssel, Adresse, Modellname. Für einen Anbieterwechsel ändert man nur die Werte der drei Variablen.