Hangfájl átírása: gpt-transcribe és Whisper
Ezen az oldalon
A leckét 2026. november 3-án írtuk át. Ez az útmutató korábban a
whisper-1modellt tárgyalta, amely elavult, és 2027. február 26-án megszűnik. Az OpenAI Fájlátírás (File transcription) útmutatója jelenleg agpt-transcribehasználatát javasolja. Ugyanakkor agpt-transcribenem szolgáltat időbélyegeket, SRT vagy VTT feliratokat, illetveverbose_jsonválaszt. Ezekre az egyedi igényekre awhisper-1marad az egyetlen lehetőség a kivezetéséig. A korábbi kód szótárakként kezelte a szegmenseket (segment["start"]), amiTypeErrorhibát okoz a Python SDK-ban; ezek objektumok (segment.start). Minden hívást ellenőriztünk azopenaiSDK 3.42.1 verziójával. Források: Fájlátírás · Átírás létrehozása · GPT-Transcribe · Elavult funkciók.
Felvétel átírása
A fájlátírás a leggyakoribb esetet fedi le: van egy kész felvételed (értekezlet, podcast, hangüzenet), és szükséged van a szövegre. Elküldöd a fájlt a /v1/audio/transcriptions végpontra, és megkapod az átírást. A még beérkező hanganyagok esetén, mint például egy mikrofonból vagy hívásból származó adatfolyam, a helyes megközelítés az élő átírás a Realtime API-n keresztül, amiről később ejtünk szót ebben a tanfolyamban.
A fájlnak legfeljebb 25 MB-osnak kell lennie, és az alábbi formátumok egyikében: mp3, mp4, mpeg, mpga, m4a, wav vagy webm.
Melyik modellt válaszd 2026 novemberében?
| Modell | Állapot | Főbb jellemzők |
|---|---|---|
gpt-transcribe | Ajánlott | Kontextus (prompt), kulcsszavak (keywords), várt nyelvek (languages), streaming átírás; 0,0045 USD/perc |
whisper-1 | Elavult, kivezetés: 2027. február 26. | Az egyetlen modell, amely időbélyegeket, verbose_json-t, SRT és VTT feliratokat, valamint angolra fordítást biztosít |
gpt-4o-transcribe, gpt-4o-mini-transcribe | Elavult, kivezetés: 2027. február 26. | A gpt-transcribe váltotta fel |
gpt-4o-transcribe-diarize | Elavult, kivezetés: 2027. február 26. | Hangszóró-azonosítás (diarized_json) |
Az első átírás
from openai import OpenAI
client = OpenAI()
with open("recording.mp3", "rb") as audio_file:
transcription = client.audio.transcriptions.create(
model="gpt-transcribe",
file=audio_file,
)
print(transcription.text)
Alapértelmezés szerint a válasz egy JSON objektum: a transcription.text tartalmazza a szöveget, a transcription.languages pedig felsorolja azokat a nyelveket, amelyeket a modell megfelelő megbízhatósággal felismert (üres lista, ha nem tudott azonosítani egyet sem).
Kontextus biztosítása a modell számára
Egy értekezletről készült felvétel tele van tulajdonnevekkel, mozaikszavakkal és belső kifejezésekkel, amelyeket a modellnek nincs oka ismernie. A gpt-transcribe három olyan tippet fogad el, amelyeket kombinálhatsz:
with open("meeting.mp3", "rb") as audio_file:
transcription = client.audio.transcriptions.create(
model="gpt-transcribe",
file=audio_file,
prompt="Vezetőségi értekezlet a Corsen AI projektről és az AC-42 szerződésről.",
keywords=["Corsen AI", "AC-42", "GDPR"],
languages=["fr", "en"],
)
print(transcription.text)
- A
promptegyetlen mondatban írja le a kontextust, a felvétel nyelvén. Ez nem rendszerutasítás; csupán egy tipp, amely irányítja a felismerést. - A
keywordsa felismerendő kifejezések listája. Minden elemhez írj be egy kulcsszót,<,>jelek vagy sortörések nélkül: az API elutasítja a teljes kérést, ha ilyet talál. - A
languagesaz ISO 639-1 kódok (fr,en,es…) segítségével adja meg a várt nyelveket. Kiváltja a régebbi modelleklanguageparaméterét: soha ne küldd el mindkettőt egyszerre.
Az átírás követése valós időben
Hosszú fájlok esetén nem kell megvárnod a végét ahhoz, hogy megjelenítsd az elejét. A stream=True beállítással az API eseményeket küld vissza a feldolgozás során, anélkül, hogy Realtime munkamenetre lenne szükség:
with open("meeting.mp3", "rb") as audio_file:
stream = client.audio.transcriptions.create(
model="gpt-transcribe",
file=audio_file,
stream=True,
)
for event in stream:
if event.type == "transcript.text.delta":
print(event.delta, end="", flush=True)
elif event.type == "transcript.text.done":
print() # teljes átírás az event.text mezőben
Időbélyegek és feliratok: whisper-1, 2027. február 26-ig
Az OpenAI útmutatója kifejezetten leszögezi: a szavankénti időbélyegekre, feliratokra és hangszóró-azonosításra vonatkozó példái elavult modelleken alapulnak. Ha szükséged van ezekre a funkciókra, a whisper-1 még elérhető 2027. február 26-ig, és ez az egyetlen modell, amely elfogadja a verbose_json és timestamp_granularities paramétereket:
with open("meeting.mp3", "rb") as audio_file:
transcription = client.audio.transcriptions.create(
model="whisper-1",
file=audio_file,
response_format="verbose_json",
timestamp_granularities=["segment"],
)
for segment in transcription.segments or []:
print(f"[{segment.start:.1f}s - {segment.end:.1f}s] {segment.text.strip()}")
A szegmensek SDK objektumok: a segment.start attribútumot olvasd, ne a segment["start"] kulcsot. A timestamp_granularities=["word"] beállítással szavankénti időbélyegek jelennek meg a transcription.words mezőben, ami kissé nagyobb késleltetéssel jár. Ugyanez a modell közvetlenül használható feliratfájlokat is előállít: ha a response_format értéke "srt" vagy "vtt", az SDK közvetlenül visszaadja a feliratfájl szövegét.
Az útmutató még nem jelölt ki helyettesítőt ezekhez a funkciókhoz. Ha a terméked függ az időbélyegektől vagy a feliratoktól, tervezz meg egy megoldást 2027. február 26. előtt.
Hosszú fájlok
A 25 MB-nál nagyobb fájlok esetén tömörítsd a hangot, vagy vágd darabokra. A dokumentáció javasolja, hogy kerüld a vágást mondatok közepén, mivel ez kontextusvesztéssel jár, és a pydub könyvtárat ajánlja a daraboláshoz (az OpenAI nem garantálja ezt a harmadik féltől származó szoftvert). Ha az előző darab végét átadod a prompt paraméterben, az segít a modellnek a folyamatosság fenntartásában; ez a paraméterhasználat az útmutatóban is szerepel:
from pydub import AudioSegment
def transcribe_long(path: str, duration_ms: int = 10 * 60 * 1000) -> str:
"""Hosszú felvétel átírása 10 perces darabokban."""
audio = AudioSegment.from_file(path)
texts: list[str] = []
for i, start in enumerate(range(0, len(audio), duration_ms)):
chunk = f"chunk_{i}.mp3"
audio[start:start + duration_ms].export(chunk, format="mp3")
options = {"prompt": texts[-1][-500:]} if texts else {} # folyamatosság
with open(chunk, "rb") as f:
result = client.audio.transcriptions.create(model="gpt-transcribe", file=f, **options)
texts.append(result.text)
return " ".join(texts)
A fix időtartamú darabolás néha félbevág egy mondatot: a csiszolt eredmény érdekében inkább csend alapján végezd a vágást.
Főbb megállapítások
- A
gpt-transcribeaz ajánlott modell fájlátírásra; awhisper-1és agpt-4o-*-transcribemodellek kivezetése 2027. február 26-án esedékes - A
prompt,keywordséslanguages(már nemlanguage) paraméterek irányítják a kifejezések és nyelvek felismerését - A
stream=Truebeállítás valós időben adja vissza az átírást (transcript.text.delta), Realtime munkamenet nélkül - Időbélyegek,
verbose_json, SRT és VTT formátumok csak awhisper-1modellel érhetők el annak kivezetéséig; a szegmenseket objektumként kezeld (segment.start) - Fájlonként maximum 25 MB: tömöríts vagy darabolj, lehetőleg csend alapján