Poradniki
·
11 min czytania
·
28 marca 2026
Jak używać OpenAI Harmony Response Format – przewodnik praktyczny
Źródło: Link
Źródło: Link
Większość ludzi używa API OpenAI jak czarnej skrzynki: wrzucasz prompt, dostajesz tekst. Problem? Nigdy nie wiesz, w jakiej formie przyjdzie odpowiedź. Raz lista wypunktowana, raz akapit, a raz JSON (ale z błędami składni).
OpenAI Harmony Response Format rozwiązuje ten problem. To mechanizm, który każe modelowi GPT zwracać dane w ściśle określonej strukturze. Bez improwizacji, bez niespodzianek. Zamiast prosić model "proszę, zwróć mi JSON", definiujesz schemat i dostajesz dokładnie to, czego potrzebujesz.
Harmony Response Format to parametr w API sztucznej inteligencji OpenAI, który wymusza na modelu językowym zwracanie odpowiedzi w konkretnym formacie JSON. Definiujesz schemat (tzw. JSON Schema), a model GPT musi się do niego dostosować – nawet jeśli naturalnie chciałby odpowiedzieć inaczej.
Przykład: prosisz o analizę opinii klienta. Bez Harmony dostajesz esej. Z Harmony otrzymujesz:
{
"sentiment": "negatywny",
"score": -0.7,
"main_issues": ["długi czas dostawy", "uszkodzone opakowanie"],
"suggested_action": "kontakt z obsługą klienta"
}
Zawsze w tej samej strukturze. Zawsze z tymi samymi kluczami. Gotowe do przetworzenia przez Twoją aplikację.
Żeby pracować z Harmony Response Format, musisz mieć:
Jeśli dopiero zaczynasz pracę z API OpenAI, sprawdź nasz przewodnik po podłączaniu ChatGPT do aplikacji – tam znajdziesz podstawy.
Pierwsza rzecz: musisz określić, jak ma wyglądać odpowiedź. Używasz do tego JSON Schema – standardu opisującego strukturę danych JSON.
Załóżmy, że budujesz chatbot AI dla sklepu internetowego i chcesz, żeby model klasyfikował zapytania klientów. Twój schemat może wyglądać tak:
{
"type": "object",
"properties": {
"kategoria": {
"type": "string",
"enum": ["zamowienie", "reklamacja", "produkt", "platnosc", "inne"]
},
"pilnosc": {
"type": "string",
"enum": ["niska", "srednia", "wysoka"]
},
"sugerowane_dzialanie": {
"type": "string"
}
},
"required": ["kategoria", "pilnosc"]
}
Co tu się dzieje:
type: object – odpowiedź będzie obiektem JSONproperties – lista pól, które mają się pojawić w odpowiedzienum – dozwolone wartości (model nie może wymyślić niczego poza tą listą)required – pola obowiązkowe (model MUSI je wypełnić)Zapisz ten schemat – będziesz go przekazywać w każdym zapytaniu do API.
Kilka zasad, które oszczędzą Ci frustracji:
type: string bez ograniczeń, użyj enum z konkretnymi wartościamidescription w schemacie pomaga modelowi zrozumieć, czego oczekujeszTeraz łączysz schemat z zapytaniem do API. W parametrze response_format przekazujesz typ json_schema i Twój schemat.
Przykład w Pythonie (używając biblioteki openai):
import openai
client = openai.OpenAI(api_key="twoj-klucz-api")
response = client.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "Jesteś asystentem klasyfikującym zapytania klientów."},
{"role": "user", "content": "Kiedy dostanę zwrot pieniędzy za zwrócony produkt?"}
],
response_format={
"type": "json_schema",
"json_schema": {
"name": "klasyfikacja_zapytania",
"schema": {
"type": "object",
"properties": {
"kategoria": {
"type": "string",
"enum": ["zamowienie", "reklamacja", "produkt", "platnosc", "inne"]
},
"pilnosc": {
"type": "string",
"enum": ["niska", "srednia", "wysoka"]
},
"sugerowane_dzialanie": {
"type": "string"
}
},
"required": ["kategoria", "pilnosc"]
}
}
}
)
print(response.choices[0].message.content)
Odpowiedź, którą dostaniesz:
{
"kategoria": "reklamacja",
"pilnosc": "srednia",
"sugerowane_dzialanie": "Przekieruj do działu zwrotów, podaj standardowy czas realizacji (5-7 dni roboczych)"
}
Dokładnie w formacie, który zdefiniowałeś. Bez dodatkowych komentarzy, bez improwizacji.
JavaScript (Node.js):
const openai = require('openai');
const client = new openai.OpenAI({
apiKey: 'twoj-klucz-api'
});
const response = await client.chat.completions.create({
model: 'gpt-4o',
messages: [
{role: 'system', content: 'Jesteś asystentem klasyfikującym zapytania klientów.'},
{role: 'user', content: 'Kiedy dostanę zwrot pieniędzy za zwrócony produkt?'}
],
response_format: {
type: 'json_schema',
json_schema: {
name: 'klasyfikacja_zapytania',
schema: { /* twój schemat */ }
}
}
});
console.log(response.choices[0].message.content);
Mechanizm jest identyczny – zmieniają się tylko szczegóły składni.
Teraz masz gwarancję, że odpowiedź zawsze będzie w tym samym formacie. Możesz bezpiecznie parsować JSON i używać danych dalej:
import json # Parsuj odpowiedź data = json.loads(response.choices[0].message.content) # Użyj danych if data['pilnosc'] == 'wysoka': wyslij_alert_do_managera(data['sugerowane_dzialanie']) elif data['kategoria'] == 'reklamacja': przekieruj_do_dzialu_zwrotow() else: zapisz_do_kolejki_standardowej()
Żadnych if "kategoria" in response, żadnego sprawdzania, czy pole istnieje. Model GPT musi zwrócić wszystkie wymagane pola – inaczej API zwróci błąd.
Nawet z Harmony czasem coś pójdzie nie tak. Dobre praktyki:
kategoria ma być z enuma, ale dostałeś coś innego, zapisz to do logówHarmony Response Format nie jest potrzebny w każdej sytuacji. Sprawdza się, gdy:
Kiedy NIE potrzebujesz Harmony:
Masz skan faktury w PDF. Chcesz wyciągnąć: numer faktury, datę, kwotę, NIP sprzedawcy. Schemat:
{
"type": "object",
"properties": {
"numer_faktury": {"type": "string"},
"data_wystawienia": {"type": "string", "format": "date"},
"kwota_brutto": {"type": "number"},
"waluta": {"type": "string", "enum": ["PLN", "EUR", "USD"]},
"nip_sprzedawcy": {"type": "string"}
},
"required": ["numer_faktury", "data_wystawienia", "kwota_brutto"]
}
Wysyłasz tekst z OCR do API, dostajesz ustrukturyzowane dane gotowe do wrzucenia do systemu księgowego.
Użytkownicy dodają komentarze na forum. Chcesz automatycznie je klasyfikować:
{
"type": "object",
"properties": {
"czy_bezpieczny": {"type": "boolean"},
"kategorie_naruszen": {
"type": "array",
"items": {
"type": "string",
"enum": ["spam", "hate_speech", "wulgaryzmy", "dezinformacja", "brak"]
}
},
"poziom_pewnosci": {"type": "number", "minimum": 0, "maximum": 1}
},
"required": ["czy_bezpieczny", "kategorie_naruszen"]
}
Model analizuje komentarz i zwraca decyzję w formacie, który Twoja aplikacja może natychmiast przetworzyć.
Masz tysiące opinii o produkcie. Chcesz je automatycznie kategoryzować:
{
"type": "object",
"properties": {
"sentiment": {"type": "string", "enum": ["pozytywny", "neutralny", "negatywny"]},
"score": {"type": "number", "minimum": -1, "maximum": 1},
"glowne_tematy": {
"type": "array",
"items": {"type": "string"}
},
"wymaga_odpowiedzi": {"type": "boolean"}
},
"required": ["sentiment", "score"]
}
Zamiast czytać każdą opinię ręcznie, dostajesz dashboard z agregatami: "72% pozytywnych, główne tematy: szybka dostawa (45%), dobra jakość (38%), wysoka cena (12%)".
Więcej o praktycznym wykorzystaniu AI w biznesie znajdziesz w artykule o wdrażaniu chatbotów AI.
Teoretycznie nie powinno się zdarzyć, ale czasem API zwraca błąd walidacji. Przyczyny:
Rozwiązanie: zacznij od prostego schematu (2-3 pola) i stopniowo go rozbudowuj.
Harmony wymusza format, nie poprawność treści. Jeśli model klasyfikuje reklamację jako "pytanie o produkt", problem leży w promptcie, nie w schemacie.
Rozwiązanie:
description w schemacie, żeby wyjaśnić, czego oczekujesz w każdym poluHarmony Response Format nie zwiększa bezpośrednio kosztów, ale złożone schematy mogą wydłużać odpowiedzi modelu (więcej tokenów wyjściowych).
Rozwiązanie:
maxLength w schemacie)Przed Harmony ludzie używali różnych trików, żeby wymusić strukturę odpowiedzi:
Harmony to oficjalny, wspierany przez OpenAI mechanizm. Jeśli potrzebujesz strukturalnych danych, to najlepszy wybór.
Jeśli dopiero zaczynasz pracę z API i chcesz poznać podstawy, sprawdź przewodnik po używaniu ChatGPT do programowania.
Nie. Działa tylko z nowszymi modelami: GPT-4o, GPT-4.5, o1, o3, o4-mini i nowszymi. Starsze modele (GPT-3.5, GPT-4 z 2023 roku) nie obsługują tego parametru. Jeśli spróbujesz użyć Harmony ze starym modelem, API zwróci błąd.
Tak, ale z ograniczeniami. Harmony świetnie sprawdza się do strukturalnych danych (JSON z polami tekstowymi do ~500 znaków). Jeśli potrzebujesz wygenerować artykuł na 2000 słów w konkretnym formacie (np. z sekcjami H2/H3), lepiej użyj szczegółowego promptu bez Harmony – model będzie miał więcej swobody w doborze słów.
Nie bezpośrednio. Płacisz za tokeny (wejściowe i wyjściowe), jak zawsze. Harmony może nieznacznie zwiększyć liczbę tokenów wyjściowych (bo model musi dopasować się do schematu), ale różnica jest minimalna – rzędu 5-10%. Większy wpływ na koszty ma wybór modelu (GPT-4.5 vs GPT-4o-mini) niż użycie Harmony.
API zwróci błąd walidacji. Model GPT spróbuje maksymalnie dopasować się do schematu, ale jeśli schemat wymaga niemożliwego (np. "zwróć datę urodzenia osoby" dla tekstu, który jej nie zawiera), dostaniesz błąd. Dlatego ważne jest, żeby schemat był realistyczny względem danych wejściowych.
Nie w tym samym zapytaniu. Harmony Response Format i function calling to dwa różne mechanizmy kontroli formatu odpowiedzi – musisz wybrać jeden. W większości przypadków Harmony jest prostszy i wystarczający. Function calling przydaje się, gdy chcesz, żeby model "wywoływał" różne funkcje w zależności od kontekstu (np. raz sprawdza pogodę, raz rezerwuje lot).
Ten poradnik to dopiero początek. W naszym kursie "Praktyczna AI" nauczysz się korzystać z ChatGPT, Claude i innych narzędzi AI w sposób systematyczny — od zera do zaawansowanego poziomu.
Sprawdź kurs →Harmony Response Format to narzędzie dla ludzi, którzy potrzebują przewidywalnych, strukturalnych odpowiedzi z API OpenAI. Definiujesz schemat JSON, model GPT musi się do niego dostosować – bez improwizacji, bez niespodzianek.
Najważniejsze punkty:
Jeśli masz dostęp do API OpenAI, stwórz prosty schemat z 2-3 polami i przetestuj na przykładowym promptcie. Zacznij od czegoś prostego (np. klasyfikacja sentymentu: pozytywny/neutralny/negatywny + score 0-1). Dopiero gdy to zadziała, rozbuduj schemat o dodatkowe pola. Testowanie na prostych przykładach oszczędzi Ci godzin debugowania później.
90 minut praktycznej wiedzy o AI. Pokaze Ci krok po kroku, jak zaczac oszczedzac 10 godzin tygodniowo dzieki sztucznej inteligencji.
Zapisz sie na webinar