Uwierzytelnianie, klucze API i organizacja
Na tej stronie
Uwierzytelnianie, klucze API i organizacja
Zanim napiszesz pierwszą linię kodu, musisz skonfigurować dostęp do API. W tej lekcji dowiesz się, jak tworzyć klucze, strukturzyć dostęp za pomocą organizacji i projektów oraz jakie środki bezpieczeństwa podjąć, aby uniknąć klasycznego koszmaru: przypadkowego wypchnięcia klucza do publicznego repozytorium, gdzie obca osoba zużyje go w ciągu jednej nocy.
Utwórz konto i uzyskaj klucz
Proces składa się z trzech kroków. Po pierwsze, przejdź na stronę platform.openai.com i utwórz konto; automatycznie otrzymasz darmowe kredyty na początkowe eksperymenty. Następnie przejdź do sekcji API Keys w panelu sterowania i wygeneruj nowy klucz. Zobaczysz ten klucz tylko raz: skopiuj go natychmiast, ale nie wklejaj go bezpośrednio do kodu.
# Twój klucz API wygląda tak (nigdy go nie udostępniaj!)
# sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Najlepsza praktyka: użyj zmiennej środowiskowej
import os
api_key = os.environ.get("OPENAI_API_KEY")
Trzecim krokiem jest zadeklarowanie zmiennej środowiskowej, co zależy od Twojej platformy. Na maszynie deweloperskiej plik .env ładowany przez python-dotenv jest często najwygodniejszym rozwiązaniem. Na serwerze preferuj zmienną środowiskową zdefiniowaną przez Twój orkiestrator lub usługę zarządzania sekretami.
# Linux / macOS — dodaj do ~/.bashrc lub ~/.zshrc
export OPENAI_API_KEY="sk-proj-your-key-here"
# Windows PowerShell
$env:OPENAI_API_KEY = "sk-proj-your-key-here"
# Plik .env (z python-dotenv)
# .env
OPENAI_API_KEY=sk-proj-your-key-here
Jaki typ klucza wybrać
Klucze projektowe, rozpoznawalne po prefiksie sk-proj-, są powiązane z konkretnym projektem i oferują najlepszą kontrolę. Będziesz ich używać w niemal każdym przypadku. SDK wykrywa je automatycznie po ustawieniu zmiennej środowiskowej, dlatego w wszystkich przykładach w tym kursie instancja OpenAI() tworzone jest bez argumentów.
from openai import OpenAI
# SDK automatycznie wykrywa OPENAI_API_KEY
client = OpenAI()
# Lub określ jawnie (niezalecane w produkcji)
client = OpenAI(api_key="sk-proj-...")
Klucze usługowe to drugi typ. Zaprojektowane dla aplikacji serwerowych wymagających podwyższonego dostępu, przyznają dodatkowe uprawnienia, a zatem wymagają szczególnej ostrożności: przechowuj je w sejfie na sekrety (secrets vault) i nigdy nie udostępniaj ich wartości stacji roboczej deweloperskiej.
Organizacje i projekty
Dostęp jest ustrukturyzowany na trzech zagnieżdżonych poziomach:
- Organization: Twoja firma lub zespół
- Project: Logiczne grupowanie (np. „Production Chatbot“, „Data Analysis“)
- API Key: Powiązany z konkretnym projektem
Jeśli należysz do wielu organizacji, określ tę, z której zamierzasz korzystać, podczas tworzenia instancji klienta:
from openai import OpenAI
# Określ organizację (przydatne, jeśli należysz do wielu)
client = OpenAI(
organization="org-xxxxxxxxxxxx",
project="proj-xxxxxxxxxxxx"
)
Poświęć czas na podzielenie swojego użycia na projekty, zamiast kierować wszystko przez jeden klucz. Zauważysz korzyści przy pierwszych oznakach kłopotów. Każdy projekt posiada własne śledzenie użycia, co pozwala przypisać koszty do konkretnej funkcji, a nie do nieprzejrzystej miesięcznej sumy. Limity szybkości (rate limits) są również rozdzielone: nocne zadanie wsadowe, które nasyci swój przydział, nie uniemożliwi chatbotowi odpowiadania klientom. Możesz następnie przypisać różnych członków do każdego projektu i, co kluczowe, unieważnić skompromitowany klucz bez przerywania działania innych aplikacji.
Nigdy nie ujawniaj swoich kluczy
Zasada jest prosta i absolutna: klucz nigdy nie pojawia się w kodzie źródłowym. Kontrast między poniższymi fragmentami mówi więcej niż długi wykład.
# ŹLE — klucz zaszyty w kodzie
client = OpenAI(api_key="sk-proj-abc123") # NIEBEZPIECZEŃSTWO!
# DOBRZE — zmienna środowiskowa
client = OpenAI() # Automatycznie odczytuje OPENAI_API_KEY
# DOBRZE — plik .env z python-dotenv
from dotenv import load_dotenv
load_dotenv()
client = OpenAI()
Konsekwencją tego jest Twój plik .gitignore, który musi wykluczać lokalne pliki konfiguracyjne przed pierwszym commitem, a nie po nim. Klucz, który został opublikowany, a następnie usunięty, nadal pozostaje w historii repozytorium.
# ZAWSZE dodaj te linie do swojego .gitignore
.env
.env.local
.env.production
*.key
Na koniec zaplanuj regularną rotację kluczy, co 90 dni. Możesz to zrobić bez przestoju: utwórz nowy klucz, zaktualizuj swoje wdrożenia, a następnie usuń stary klucz dopiero wtedy, gdy nic już z niego nie korzysta.
Zweryfikuj swoją konfigurację
Zanim przejdziesz dalej, uruchom ten skrypt. Sprawdza on obecność klucza, wyświetla jego skróconą wersję, aby potwierdzić, że jest to właściwy klucz, a następnie wykonuje rzeczywiste wywołanie. Uruchamiaj ten test ponownie za każdym razem, gdy środowisko zachowuje się dziwnie.
from openai import OpenAI
import os
def verify_configuration():
"""Zweryfikuj, czy konfiguracja API jest poprawna."""
# Sprawdź obecność klucza
api_key = os.environ.get("OPENAI_API_KEY")
if not api_key:
print("BŁĄD: OPENAI_API_KEY nie jest zdefiniowane")
return False
print(f"Wykryto klucz: {api_key[:8]}...{api_key[-4:]}")
# Przetestuj połączenie
try:
client = OpenAI()
response = client.responses.create(
model="gpt-5.6-terra",
input="Reply only: OK"
)
print(f"Połączenie udane: {response.output_text}")
return True
except Exception as e:
print(f"BŁĄD połączenia: {e}")
return False
verify_configuration()
# Oczekiwany wynik:
# Wykryto klucz: sk-proj-...xxxx
# Połączenie udane: OK
Kluczowe wnioski
- Używaj kluczy projektowych (
sk-proj-...) dla każdej aplikacji - Przechowuj klucze w zmiennych środowiskowych, nigdy w kodzie
- Organizuj swój dostęp zgodnie z hierarchią Organization → Project → Key
- Przeprowadzaj regularną rotację kluczy (co 90 dni)
- Zawsze dodawaj
.envdo swojego.gitignore