Инсталиране на Python SDK
На тази страница
Инсталиране на Python SDK
Python SDK openai е официалната библиотека за взаимодействие с API. В този урок ще Ви преведем през процеса на инсталиране и ще настроим чиста структура на проекта, която ще използвате през остатъка от курса.
Предпоставки и инсталиране
Необходим Ви е Python 3.10 или по-нова версия – минималното изискване за openai SDK (версия 3.42.1 към 2 ноември 2026 г., според PyPI), мениджър на пакети (pip или uv) и API ключът, който получихте в предишния урок. Започнете с потвърждаване на Вашия интерпретатор, тъй като разработческите машини често поддържат множество версии:
python --version
# Python 3.12.4
Инсталирането става с една команда: pip install openai, или uv pip install openai, ако използвате uv, което е значително по-бързо. Въпреки това, направете си навик да работите във виртуална среда. Това предотвратява често срещания сценарий, при който шест месеца по-късно откривате, че два проекта изискват несъвместими версии на една и съща библиотека.
# Създаване на виртуална среда
python -m venv .venv
# Активиране (Linux/macOS)
source .venv/bin/activate
# Активиране (Windows)
.venv\Scripts\activate
# Инсталиране на SDK
pip install openai
Два спътника се появяват в почти всеки проект и заслужават да бъдат инсталирани заедно със SDK. Pydantic помага за дефиниране на схеми за структуриран изход, което ще видите по-късно; python-dotenv зарежда файла .env във променливи на средата.
# Инсталиране с поддръжка за Pydantic dataclasses
pip install openai pydantic
# Инсталиране с python-dotenv за променливи на средата
pip install openai python-dotenv
Накрая, проверете дали импортирането работи и отбележете инсталираната версия. Това е първата информация, която трябва да предоставите, ако отворите билет за поддръжка.
import openai
print(f"OpenAI SDK version: {openai.__version__}")
# Output: OpenAI SDK version: 1.68.0 (or newer)
Един клиент, всички API
SDK се върти около един единствен клиентски обект, който излага цялата платформа чрез подмодули. Не е необходимо да създавате нищо ново, за да превключите от генериране на текст към вграждания или модериране.
from openai import OpenAI
client = OpenAI()
# Responses API (текст, извикване на функции, структуриран изход)
client.responses.create(...)
# Chat Completions API (остаряло)
client.chat.completions.create(...)
# Вграждания (Embeddings)
client.embeddings.create(...)
# Изображения
client.images.generate(...)
# Аудио
client.audio.transcriptions.create(...)
client.audio.speech.create(...)
# Модериране
client.moderations.create(...)
Конфигуриране на клиента за Вашия контекст
Стойностите по подразбиране на SDK са подходящи за експерименти, но не са достатъчни за уеб приложения. Таймаутът по подразбиране е десет минути: в HTTP API, от което се очаква да отговори за секунди, това означава, че заседнала заявка ангажира работен процес твърде дълго. Намалете го и увеличете броя на автоматичните повторни опити, който по подразбиране е два.
from openai import OpenAI
client = OpenAI(
timeout=60.0, # 60 секунди (по подразбиране: 10 минути)
max_retries=3, # 3 опита при грешка (по подразбиране: 2)
)
Параметърът base_url отговаря на друга нужда: насочване на обажданията през корпоративен прокси, който регистрира изходящия трафик, или към услуга, излагаща съвместимо API.
# Полезно за корпоративни проксита или съвместими API
client = OpenAI(
base_url="https://your-proxy.company.com/v1"
)
И накрая, ако Вашето приложение разчита на asyncio – FastAPI, aiohttp и подобни – използвайте AsyncOpenAI. Синхронният клиент би блокирал цикъла на събитията по време на генерирането, което отрича ползите от асинхронния код.
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
# Използване с await
import asyncio
async def main():
response = await async_client.responses.create(
model="gpt-5.6-terra",
input="Hello!"
)
print(response.output_text)
asyncio.run(main())
# Output: Hello! How can I help you today?
Структурирайте Вашия проект
Приемете организация, която изолира конфигурацията на клиента от останалата част от кода Ви още от самото начало. Това избягва разпръскването на десетки обаждания OpenAI() из целия Ви проект, всяко със собствените си настройки.
my-project/
├── .env # API ключ (НИКОГА не комитвайте в git)
├── .gitignore # Включва .env
├── requirements.txt # Зависимости
├── src/
│ ├── __init__.py
│ ├── client.py # Конфигурация на OpenAI клиента
│ └── main.py # Точка на влизане
└── tests/
└── test_api.py
Файлът src/client.py централизира фабриката за клиенти: в деня, в който промените таймаута или добавите прокси, трябва да модифицирате само едно място.
from openai import OpenAI
from dotenv import load_dotenv
load_dotenv()
def get_client() -> OpenAI:
"""Връща конфигуриран OpenAI клиент."""
return OpenAI(
max_retries=3,
timeout=30.0
)
А requirements.txt фиксира минималните очаквани версии:
openai>=1.60.0
python-dotenv>=1.0.0
pydantic>=2.0.0
Три често срещани грешки
ModuleNotFoundError за openai почти винаги сигнализира за неактивна виртуална среда или такава, различна от тази, в която сте инсталирали пакета. Локализирайте интерпретатора, който действително се използва, с which python на Linux и macOS, или where python на Windows, след което преинсталирайте с pip install --upgrade openai. AuthenticationError сочи към променливата на средата: отпечатайте os.environ.get("OPENAI_API_KEY", "NOT DEFINED"), за да изключите проблеми – файлът .env не се зарежда, ако load_dotenv() не е извикан преди създаването на екземпляра на клиента. Накрая, грешка относно неизвестен параметър обикновено показва, че SDK е твърде стар за функцията, която използвате: pip install --upgrade openai решава това.
Ключови изводи
- Инсталирайте SDK с
pip install openaiвъв виртуална среда - Клиентът
OpenAI()е точката на влизане за всички API - Използвайте
AsyncOpenAI()за асинхронни приложения - Конфигурирайте таймаута и повторните опити според Вашите нужди
- Структурирайте проекта си с файл
.envи централизиран клиент