Medya dosyalarıyla istemde bulunma


ai.google.dev'de göster Google Colab'de çalıştır Kaynağı GitHub'da görüntüle

Gemini API, çok modlu istem olarak da bilinen metin, resim, ses ve video verileriyle istem göndermeyi destekler. Yani bu tür medya dosyalarını istemlerinize ekleyebilirsiniz. Küçük dosyalar için istem sağlarken Gemini modelini doğrudan yerel bir dosyaya yönlendirebilirsiniz. Daha büyük dosyaları, istemlere dahil etmeden önce Dosya API'si ile yükleyin.

File API, her bir dosyanın boyutu 2 GB'ı aşmayacak şekilde proje başına 20 GB'a kadar dosya depolamanıza olanak tanır. Dosyalar 48 saat boyunca saklanır ve bu süre içinde oluşturma işlemi için API anahtarınızla erişilebilir ve API'den indirilemez. Files API, Gemini API'nin kullanılabildiği tüm bölgelerde ücretsiz olarak kullanılabilir.

File API, model.generateContent veya model.streamGenerateContent ile içerik oluşturmak için kullanılabilecek girişleri işler. Geçerli dosya biçimleri (MIME türleri) ve desteklenen modeller hakkında bilgi için Desteklenen dosya biçimleri bölümüne bakın.

Bu kılavuzda, medya dosyalarını yüklemek ve Gemini API'ye yapılan bir GenerateContent çağrısına dahil etmek için File API'nin nasıl kullanılacağı gösterilmektedir. Daha fazla bilgi için kod örneklerine bakın.

Başlamadan önce: Projenizi ve API anahtarınızı oluşturun

Gemini API'yi (veya File API'yi) çağırmadan önce projenizi ayarlamanız ve API anahtarınızı yapılandırmanız gerekir.

Resimlerle istem gönderme

Bu eğiticide, File API'yi kullanarak örnek bir görüntü yükleyecek ve ardından bu resmi içerik oluşturmak için kullanacaksınız.

Resim dosyası yükleyin

Kendi dosyanızı nasıl yükleyeceğinizi öğrenmek için Ek bölümüne bakın.

  1. Yüklemek için örnek bir resim hazırlayın:

      curl -o image.jpg https://storage.googleapis.com/generativeai-downloads/images/jetpack.jpg

  2. İlgili dosyaya media.upload kullanarak diğer API çağrılarıyla erişebilmek için dosyayı yükleyin:

    sample_file = genai.upload_file(path="image.jpg",
                            display_name="Sample drawing")

print(f"Uploaded file '{sample_file.display_name}' as: {sample_file.uri}")

response, yüklenen resmin belirtilen display_name ile depolandığını ve Gemini API çağrılarında dosyaya referans vermek için bir uri içerdiğini gösterir. Yüklenen dosyaların URI'lerle nasıl eşlendiğini izlemek için response kullanın.

Kullanım alanınıza bağlı olarak URI'ları dict veya veritabanı gibi yapılarda depolayabilirsiniz.

Resim dosyasının meta verilerini alma

Dosyayı yükledikten sonra, API'nin dosyayı başarıyla depoladığını doğrulayabilir ve SDK üzerinden files.get yöntemini çağırarak dosyanın meta verilerini alabilirsiniz.

Bu yöntem, API anahtarınıza bağlı Google Cloud projesiyle ilişkili yüklenen bir dosyanın meta verilerini almanızı sağlar. Yalnızca name (ve buna bağlı olarak uri) benzersizdir. Yalnızca benzersizliği kendiniz yönetiyorsanız dosyaları tanımlamak için display_name kullanın.

file = genai.get_file(name=sample_file.name)
print(f"Retrieved file '{file.display_name}' as: {sample_file.uri}")

Yüklenen resim dosyasını kullanarak içerik oluşturun

Resmi yükledikten sonra, yanıtta uri öğesine referans veren GenerateContent istekleri gönderebilirsiniz (dosyayı yükleyerek veya doğrudan dosyanın meta verilerini alarak).

Bu örnekte, metinle başlayan bir istem ve ardından yüklenen dosya için URI referansı oluşturuyorsunuz:

# The Gemini 1.5 models are versatile and work with multimodal prompts
model = genai.GenerativeModel(model_name="models/gemini-1.5-flash")

response = model.generate_content([sample_file, "Describe the image with a creative description."])

Markdown(">" + response.text)

Resim dosyasını silme

Dosyalar 48 saat sonra otomatik olarak silinir. Bunları, SDK aracılığıyla files.delete kullanarak manuel olarak da silebilirsiniz.

genai.delete_file(sample_file.name)
print(f'Deleted {sample_file.display_name}.')

Videolarla istem oluşturma

Bu eğiticide, File API'yi kullanarak örnek bir video yükleyecek ve ardından bu videoyu kullanarak içerik oluşturacaksınız.

Video dosyası yükleyin

Gemini API, video dosyası biçimlerini doğrudan kabul eder. Bu örnekte "Big Buck Bunny" kısa filmi kullanılmaktadır.

"Big Buck Bunny", (c) telif hakkı 2008, Blender Foundation / www.bigbuckbunny.org adresindedir ve Creative Commons Atıf 3.0 Lisansı kapsamında lisanslanmıştır.

Kendi dosyanızı nasıl yükleyeceğinizi öğrenmek için Ek bölümüne bakın.

  1. Örnek video dosyasını yükleme için hazırlayın:

    wget https://download.blender.org/peach/bigbuckbunny_movies/BigBuckBunny_320x180.mp4

  2. İlgili dosyaya media.upload kullanarak diğer API çağrılarıyla erişebilmek için dosyayı yükleyin:

    video_file_name = "BigBuckBunny_320x180.mp4"

print(f"Uploading file...")
video_file = genai.upload_file(path=video_file_name)
print(f"Completed upload: {video_file.uri}")

Video dosyasının yükleme durumunu doğrulama

SDK üzerinden files.get yöntemini çağırarak API'nin video dosyasını başarıyla yüklediğini doğrulayın.

Video dosyalarında File API'den bir State alanı bulunur. Yüklenen bir video, çıkarım için hazır olana kadar PROCESSING durumunda kalır. Model çıkarımı için yalnızca ACTIVE dosyaları kullanılabilir.

import time

while video_file.state.name == "PROCESSING":
    print('.', end='')
    time.sleep(10)
    video_file = genai.get_file(video_file.name)

if video_file.state.name == "FAILED":
  raise ValueError(video_file.state.name)

Video dosyasının meta verilerini alma

Yüklenen video dosyasının meta verilerini istediğiniz zaman SDK üzerinden files.get yöntemini çağırarak alabilirsiniz.

Bu yöntem, API anahtarınıza bağlı Google Cloud projesiyle ilişkili yüklenen bir dosyanın meta verilerini almanızı sağlar. Yalnızca name (ve buna bağlı olarak uri) benzersizdir. Yalnızca benzersizliği kendiniz yönetiyorsanız dosyaları tanımlamak için display_name kullanın.

file = genai.get_file(name=video_file.name)
print(f"Retrieved file '{file.display_name}' as: {video_file.uri}")

Yüklenen video dosyasını kullanarak içerik oluşturun

Videoyu yükledikten sonra, yanıtta uri öğesine referans veren GenerateContent istekleri gönderebilirsiniz (dosyayı yükleyerek veya doğrudan dosyanın meta verilerini alarak).

Video üzerinde çıkarım çalıştırmadan önce video dosyasının yükleme durumunu doğruladığınızdan (yukarıdaki bölüm) emin olun.

# Create the prompt.
prompt = "Describe this video."

# The Gemini 1.5 models are versatile and work with multimodal prompts
model = genai.GenerativeModel(model_name="models/gemini-1.5-flash")

# Make the LLM request.
print("Making LLM inference request...")
response = model.generate_content([video_file, prompt],
                                  request_options={"timeout": 600})
print(response.text)

Video dosyasını silme

Dosyalar 48 saat sonra otomatik olarak silinir. Bunları, SDK aracılığıyla files.delete kullanarak manuel olarak da silebilirsiniz.

genai.delete_file(file_response.name)
print(f'Deleted file {file_response.uri}')

Desteklenen dosya biçimleri

Gemini modelleri, birden fazla dosya biçimiyle istemleri destekler. Bu bölümde, özellikle resim, ses, video ve düz metin dosyaları olmak üzere istem için genel medya biçimlerinin kullanımıyla ilgili dikkat edilmesi gereken noktalar açıklanmaktadır. Aşağıdaki tabloda gösterildiği gibi, yalnızca belirli model sürümleriyle istemde bulunmak için medya dosyalarını kullanabilirsiniz.

Model Resimler Ses Video Düz metin
Gemini 1.5 Pro (sürüm 008 ve sonraki sürümler) ✔ (maksimum 3.600 resim dosyası) ✔ ✔ ✔

Resim biçimleri

Gemini 1.5 modelleriyle istemde bulunmak için resim verilerini kullanabilirsiniz. Resimleri istem amacıyla kullandığınızda bu resimler aşağıdaki sınırlamalara ve şartlara tabidir:

  • Resimler aşağıdaki resim verisi MIME türlerinden birinde olmalıdır:
    • PNG - resim/png
    • JPEG - resim/jpeg
    • WEBP - resim/webp
    • HEIC - resim/heik
    • HEIF - resim/heif
  • Gemini 1.5 modelleri için maksimum 3.600 resim.
  • Bir resimdeki piksel sayısıyla ilgili belirli bir sınır yoktur. Ancak, daha büyük resimler orijinal en boy oranları korunarak maksimum 3072 x 3072 çözünürlüğe sığacak şekilde küçültülür.

Ses biçimleri

Gemini 1.5 modelleriyle istemde bulunmak için ses verilerini kullanabilirsiniz. İstemlerde ses kullandığınızda bu kullanımlar aşağıdaki kısıtlama ve şartlara tabidir:

  • Ses verileri, aşağıdaki yaygın ses biçimi MIME türlerinde desteklenir:
    • WAV - ses/wav
    • MP3 - ses/mp3
    • AIFF - ses/aiff
    • AAC - ses/aac
    • OGG Vorbis - ses/ogg
    • FLAC - ses/flac
  • Tek bir istemde desteklenen maksimum ses verisi uzunluğu 9,5 saattir.
  • Ses dosyaları 16 Kb/sn veri çözünürlüğüne indirilerek yeniden örneklenir ve birden fazla ses kanalı tek bir kanalda birleştirilir.
  • Tek bir istemdeki ses dosyası sayısıyla ilgili belirli bir sınır yoktur.Ancak tek bir istemdeki tüm ses dosyalarının toplam uzunluğu 9, 5 saati aşamaz.

Video biçimleri

Gemini 1.5 modelleriyle istem göndermek için video verilerini kullanabilirsiniz.

  • Video verileri, aşağıdaki yaygın video biçimi MIME türlerinde desteklenir:

    • video/mp4
    • video/mpeg
    • video/taşıma
    • video/avi
    • video/x-flv
    • video/mpg
    • video/webm
    • video/wmv
    • video/3Gpp

  • File API hizmeti, videoları saniyede 1 kare (FPS) hızında görüntüler halinde örnekler ve en iyi çıkarım kalitesini sağlamak için değiştirilebilir. Çözünürlük ve kaliteden bağımsız olarak tek tek resimler 258 jeton alır.

Düz metin biçimleri

File API, aşağıdaki MIME türlerine sahip düz metin dosyalarının yüklenmesini destekler:

  • metin/düz
  • text/html
  • text/css
  • text/javascript
  • application/x-javascript
  • metin/x-typescript
  • uygulama/x-typescript
  • metin/csv
  • metin/işaretleme
  • metin/x-python
  • application/x-python-code
  • application/json
  • text/xml
  • uygulama/rtf
  • metin/rtf

MIME türü listede olmayan düz metin dosyaları için yukarıdaki MIME türlerinden birini manuel olarak belirtmeyi deneyebilirsiniz.

Ek: Colab'e dosya yükleme

Bu not defteri, internetten indirilen dosyalarla birlikte File API'yi kullanır. Bunu Colab'de çalıştırıyorsanız ve kendi dosyalarınızı kullanmak istiyorsanız öncelikle bunları Colab örneğine yüklemeniz gerekir.

Öncelikle sol kenar çubuğunda Dosyalar'ı, ardından Yükle düğmesini tıklayın:

Ardından, bu dosyayı File API'ye (Dosya API) yükleyeceksiniz. Aşağıdaki kod hücresinin formuna, yüklediğiniz dosyanın dosya adını girin, dosya için uygun bir görünen ad girin ve hücreyi çalıştırın.

my_filename = "gemini_logo.png" # @param {type:"string"}
my_file_display_name = "Gemini Logo" # @param {type:"string"}

my_file = genai.upload_file(path=my_filename,
                            display_name=my_file_display_name)
print(f"Uploaded file '{my_file.display_name}' as: {my_file.uri}")