Rozumienie mowy

Gemini może analizować i interpretować dane wejściowe audio, co umożliwia takie zastosowania:

  • opisywać, streszczać lub odpowiadać na pytania dotyczące treści audio;
  • Prześlij transkrypcję nagrania.
  • analizować wybrane segmenty dźwięku;

Z tego przewodnika dowiesz się, jak użyć interfejsu Gemini API do wygenerowania odpowiedzi tekstowej na wejście audio.

Zanim zaczniesz

Zanim wywołasz interfejs Gemini API, upewnij się, że masz zainstalowany wybrany pakiet SDK oraz skonfigurowany i gotowy do użycia klucz interfejsu Gemini API.

Dźwięk wejściowy

Dane audio możesz przesyłać do Gemini na te sposoby:

Przesyłanie pliku audio

Do przesyłania plików audio możesz użyć interfejsu Files API. Zawsze używaj interfejsu Files API, gdy łączny rozmiar żądania (w tym pliki, prompt tekstowy, instrukcje systemu itp.) przekracza 20 MB.

Ten kod przesyła plik audio, a potem używa go w wywołaniu funkcji generateContent.

from google import genai

client = genai.Client(api_key="GOOGLE_API_KEY")

myfile = client.files.upload(file="path/to/sample.mp3")

response = client.models.generate_content(
    model="gemini-2.0-flash", contents=["Describe this audio clip", myfile]
)

print(response.text)
import {
  GoogleGenAI,
  createUserContent,
  createPartFromUri,
} from "@google/genai";

const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });

async function main() {
  const myfile = await ai.files.upload({
    file: "path/to/sample.mp3",
    config: { mimeType: "audio/mp3" },
  });

  const response = await ai.models.generateContent({
    model: "gemini-2.0-flash",
    contents: createUserContent([
      createPartFromUri(myfile.uri, myfile.mimeType),
      "Describe this audio clip",
    ]),
  });
  console.log(response.text);
}

await main();
file, err := client.UploadFileFromPath(ctx, "path/to/sample.mp3", nil)
if err != nil {
    log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)

model := client.GenerativeModel("gemini-2.0-flash")
resp, err := model.GenerateContent(ctx,
    genai.FileData{URI: file.URI},
    genai.Text("Describe this audio clip"))
if err != nil {
    log.Fatal(err)
}

printResponse(resp)
AUDIO_PATH="path/to/sample.mp3"
MIME_TYPE=$(file -b --mime-type "${AUDIO_PATH}")
NUM_BYTES=$(wc -c < "${AUDIO_PATH}")
DISPLAY_NAME=AUDIO

tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "https://generativelanguage.googleapis.com/upload/v1beta/files?key=${GOOGLE_API_KEY}" \
  -D upload-header.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${AUDIO_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri

# Now generate content using that file
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GOOGLE_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"text": "Describe this audio clip"},
          {"file_data":{"mime_type": "${MIME_TYPE}", "file_uri": '$file_uri'}}]
        }]
      }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json

Więcej informacji o pracy z plikami multimedialnymi znajdziesz w artykule Interfejs Files API.

Przekazywanie danych audio w ramach tekstu

Zamiast przesyłać plik audio, możesz przekazać dane audio w ramach żądania do generateContent:

from google.genai import types

with open('path/to/small-sample.mp3', 'rb') as f:
    audio_bytes = f.read()

response = client.models.generate_content(
  model='gemini-2.0-flash',
  contents=[
    'Describe this audio clip',
    types.Part.from_bytes(
      data=audio_bytes,
      mime_type='audio/mp3',
    )
  ]
)

print(response.text)
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
const base64AudioFile = fs.readFileSync("path/to/small-sample.mp3", {
  encoding: "base64",
});

const contents = [
  { text: "Please summarize the audio." },
  {
    inlineData: {
      mimeType: "audio/mp3",
      data: base64AudioFile,
    },
  },
];

const response = await ai.models.generateContent({
  model: "gemini-2.0-flash",
  contents: contents,
});
console.log(response.text);
// Initialize a Gemini model appropriate for your use case.
model := client.GenerativeModel("gemini-2.0-flash")

bytes, err := os.ReadFile("path/to/small-sample.mp3")
if err != nil {
  log.Fatal(err)
}

prompt := []genai.Part{
  genai.Blob{MIMEType: "audio/mp3", Data: bytes},
  genai.Text("Please summarize the audio."),
}

// Generate content using the prompt.
resp, err := model.GenerateContent(ctx, prompt...)
if err != nil {
  log.Fatal(err)
}

// Handle the response of generated text
for _, c := range resp.Candidates {
  if c.Content != nil {
    fmt.Println(*c.Content)
  }
}

Warto pamiętać o kilku kwestiach dotyczących danych dźwięku wbudowanego:

  • Maksymalny rozmiar żądania to 20 MB, w tym tekstowe prompty, instrukcje systemu i pliki dostarczone w postaci inline. Jeśli rozmiar pliku przekroczy 20 MB, łączny rozmiar żądania, użyj interfejsu Files API, aby przesłać plik audio, który ma być użyty w żądaniu.
  • Jeśli używasz sampli audio wielokrotnie, bardziej wydajne jest przesłanie pliku audio.

Pobieranie transkrypcji

Aby uzyskać transkrypcję danych audio, po prostu poproś o nią w promptzie:

myfile = client.files.upload(file='path/to/sample.mp3')
prompt = 'Generate a transcript of the speech.'

response = client.models.generate_content(
  model='gemini-2.0-flash',
  contents=[prompt, myfile]
)

print(response.text)
import {
  GoogleGenAI,
  createUserContent,
  createPartFromUri,
} from "@google/genai";

const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
const myfile = await ai.files.upload({
  file: "path/to/sample.mp3",
  config: { mimeType: "audio/mpeg" },
});

const result = await ai.models.generateContent({
  model: "gemini-2.0-flash",
  contents: createUserContent([
    createPartFromUri(myfile.uri, myfile.mimeType),
    "Generate a transcript of the speech.",
  ]),
});
console.log("result.text=", result.text);
// Initialize a Gemini model appropriate for your use case.
model := client.GenerativeModel("gemini-2.0-flash")

// Create a prompt using text and the URI reference for the uploaded file.
prompt := []genai.Part{
  genai.FileData{URI: sampleAudio.URI},
  genai.Text("Generate a transcript of the speech."),
}

// Generate content using the prompt.
resp, err := model.GenerateContent(ctx, prompt...)
if err != nil {
  log.Fatal(err)
}

// Handle the response of generated text
for _, c := range resp.Candidates {
  if c.Content != nil {
    fmt.Println(*c.Content)
  }
}

Odwoływanie się do sygnatur czasowych

Możesz odwoływać się do określonych sekcji pliku audio, używając sygnatur czasowych w formie MM:SS. Na przykład ten prompt prosi o transkrypcję, która:

  • Rozpoczyna się po 2 minutach i 30 sekundach od początku pliku.
  • Kończy się w 3 minucie i 29 sekundach od początku pliku.

# Create a prompt containing timestamps.
prompt = "Provide a transcript of the speech from 02:30 to 03:29."
// Create a prompt containing timestamps.
const prompt = "Provide a transcript of the speech from 02:30 to 03:29."
// Create a prompt containing timestamps.
prompt := []genai.Part{
    genai.FileData{URI: sampleAudio.URI},
    genai.Text("Provide a transcript of the speech from 02:30 to 03:29."),
}

Liczba tokenów

Aby uzyskać liczbę tokenów w pliku audio, wywołaj metodę countTokens. Na przykład:

response = client.models.count_tokens(
  model='gemini-2.0-flash',
  contents=[myfile]
)

print(response)
import {
  GoogleGenAI,
  createUserContent,
  createPartFromUri,
} from "@google/genai";

const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
const myfile = await ai.files.upload({
  file: "path/to/sample.mp3",
  config: { mimeType: "audio/mpeg" },
});

const countTokensResponse = await ai.models.countTokens({
  model: "gemini-2.0-flash",
  contents: createUserContent([
    createPartFromUri(myfile.uri, myfile.mimeType),
  ]),
});
console.log(countTokensResponse.totalTokens);
tokens, err := model.CountTokens(ctx, genai.FileData{URI: sampleAudio.URI})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("File %s is %d tokens", sampleAudio.DisplayName, tokens.TotalTokens)

Obsługiwane formaty audio

Gemini obsługuje te typy MIME formatu audio:

  • WAV – audio/wav
  • MP3 – audio/mp3
  • AIFF – audio/aiff
  • AAC – audio/aac
  • OGG Vorbis – audio/ogg
  • FLAC – audio/flac

Szczegóły techniczne dotyczące dźwięku

  • Gemini reprezentuje każdą sekundę dźwięku za pomocą 32 tokenów. Na przykład 1 minuta dźwięku to 1920 tokenów.
  • Gemini może udzielać odpowiedzi tylko na wypowiedzi w języku angielskim.
  • Gemini może „rozumieć” elementy niewerbalne, takie jak śpiew ptaków czy syreny.
  • Maksymalna obsługiwana długość danych audio w pojedynczym promptu to 9,5 godziny. Gemini nie ogranicza liczby plików audio w pojedynczym promptzie, ale łączna długość wszystkich plików audio w pojedynczym promptzie nie może przekraczać 9,5 godziny.
  • Gemini zmniejsza rozdzielczość plików audio do 16 kb/s.
  • Jeśli źródło dźwięku zawiera wiele kanałów, Gemini połączy je w jeden kanał.

Co dalej?

Z tego przewodnika dowiesz się, jak generować tekst w odpowiedzi na dane audio. Więcej informacji znajdziesz w tych materiałach:

  • Strategie wyświetlania promptów dotyczących plików: interfejs Gemini API obsługuje prompty z tekstem, obrazem, dźwiękiem i danymi wideo, które są też nazywane promptami multimodalnymi.
  • Instrukcje systemowe: instrukcje systemowe pozwalają kierować działaniem modelu na podstawie konkretnych potrzeb i przypadków użycia.
  • Wskazówki dotyczące bezpieczeństwa: modele generatywnej AI czasami generują nieoczekiwane wyniki, np. niedokładne, stronnicze lub obraźliwe. Przetwarzanie końcowe i sprawdzanie przez weryfikatorów są niezbędne do ograniczenia ryzyka szkód wynikających z takich danych wyjściowych.