Embeddings

Osadzanie to numeryczna reprezentacja tekstu wejściowego, która otwiera wiele unikalnych przypadków użycia, takich jak klastrowanie, pomiar podobieństwa i wyszukiwanie informacji. Więcej informacji znajdziesz w przewodniku po embeddingach.

W przeciwieństwie do modeli generatywnej AI, które tworzą nowe treści, model Gemini Embedding ma tylko przekształcać format danych wejściowych w reprezentację numeryczną. Google odpowiada za udostępnienie modelu osadzania, który przekształca format danych wejściowych na wymagany format numeryczny, ale użytkownicy ponoszą pełną odpowiedzialność za wprowadzane dane i powstałe osadzanie. Korzystając z modelu Gemini Embedding, potwierdzasz, że masz wymagane prawa do treści, które przesyłasz. Nie twórz treści naruszających prawa własności intelektualnej lub prawo do prywatności innych osób. Korzystanie z tej usługi podlega naszym Zasadom dotyczącym niedozwolonych zastosowańWarunkom korzystania z usług Google.

Metoda: models.embedContent

Generuje wektor dystrybucyjny tekstu z danych wejściowych Content za pomocą określonego modelu Gemini Embedding.

Punkt końcowy

post https://generativelanguage.googleapis.com/v1beta/{model=models/*}:embedContent

Parametry ścieżki

model string

Wymagane. Nazwa zasobu modelu. Służy on jako identyfikator modelu.

Ta nazwa powinna pasować do nazwy modelu zwróconej przez metodę models.list.

Format: models/{model}. Przyjmuje postać models/{model}.

Treść żądania

Treść żądania zawiera dane o następującej strukturze:

Pola
content object (Content)

Wymagane. Treści do umieszczenia. Zostaną zliczone tylko pola parts.text.

taskType enum (TaskType)

Opcjonalnie. Opcjonalny typ zadania, do którego będą używane wektory. Nieobsługiwane w starszych modelach (models/embedding-001).

title string

Opcjonalnie. Opcjonalny tytuł tekstu. Ma zastosowanie tylko wtedy, gdy TaskType to RETRIEVAL_DOCUMENT.

Uwaga: określenie wartości title dla parametru RETRIEVAL_DOCUMENT zapewnia lepszą jakość osadzania na potrzeby wyszukiwania.

outputDimensionality integer

Opcjonalnie. Opcjonalny zredukowany wymiar wyjściowego wektora dystrybucyjnego. Jeśli ta opcja jest ustawiona, nadmierne wartości w osadzaniu wyjściowym są obcinane od końca. Obsługiwane tylko przez nowsze modele od 2024 r. Jeśli używasz starszego modelu (models/embedding-001), nie możesz ustawić tej wartości.

Przykładowe żądanie

Python

from google import genai
from google.genai import types

client = genai.Client()
text = "Hello World!"
result = client.models.embed_content(
    model="gemini-embedding-001",
    contents=text,
    config=types.EmbedContentConfig(output_dimensionality=10),
)
print(result.embeddings)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const text = "Hello World!";
const result = await ai.models.embedContent({
  model: "gemini-embedding-001",
  contents: text,
  config: { outputDimensionality: 10 },
});
console.log(result.embeddings);

Przeczytaj

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

text := "Hello World!"
outputDim := int32(10)
contents := []*genai.Content{
	genai.NewContentFromText(text, genai.RoleUser),
}
result, err := client.Models.EmbedContent(ctx, "gemini-embedding-001", 
	contents, &genai.EmbedContentConfig{
		OutputDimensionality: &outputDim,
})
if err != nil {
	log.Fatal(err)
}

embeddings, err := json.MarshalIndent(result.Embeddings, "", "  ")
if err != nil {
	log.Fatal(err)
}
fmt.Println(string(embeddings))

Muszla

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"model": "models/gemini-embedding-001",
     "content": {
     "parts":[{
     "text": "What is the meaning of life?"}]}
    }'

Treść odpowiedzi

W przypadku powodzenia treść odpowiedzi obejmuje wystąpienie elementu EmbedContentResponse.

Metoda: models.batchEmbedContents

Generuje wiele wektorów osadzania z danych wejściowych Content, które składają się z grupy ciągów znaków reprezentowanych jako obiekty EmbedContentRequest.

Punkt końcowy

post https://generativelanguage.googleapis.com/v1beta/{model=models/*}:batchEmbedContents

Parametry ścieżki

model string

Wymagane. Nazwa zasobu modelu. Służy on jako identyfikator modelu.

Ta nazwa powinna pasować do nazwy modelu zwróconej przez metodę models.list.

Format: models/{model}. Przyjmuje postać models/{model}.

Treść żądania

Treść żądania zawiera dane o następującej strukturze:

Pola
requests[] object (EmbedContentRequest)

Wymagane. Umieść żądania w pakiecie. Model w każdym z tych żądań musi być zgodny z modelem określonym w BatchEmbedContentsRequest.model.

Przykładowe żądanie

Python

from google import genai
from google.genai import types

client = genai.Client()
texts = [
    "What is the meaning of life?",
    "How much wood would a woodchuck chuck?",
    "How does the brain work?",
]
result = client.models.embed_content(
    model="gemini-embedding-001",
    contents=texts,
    config=types.EmbedContentConfig(output_dimensionality=10),
)
print(result.embeddings)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const texts = [
  "What is the meaning of life?",
  "How much wood would a woodchuck chuck?",
  "How does the brain work?",
];
const result = await ai.models.embedContent({
  model: "gemini-embedding-001",
  contents: texts,
  config: { outputDimensionality: 10 },
});
console.log(result.embeddings);

Przeczytaj

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

contents := []*genai.Content{
	genai.NewContentFromText("What is the meaning of life?", genai.RoleUser),
	genai.NewContentFromText("How much wood would a woodchuck chuck?", genai.RoleUser),
	genai.NewContentFromText("How does the brain work?", genai.RoleUser),
}

outputDim := int32(10)
result, err := client.Models.EmbedContent(ctx, "gemini-embedding-001", contents, &genai.EmbedContentConfig{
	OutputDimensionality: &outputDim,
})
if err != nil {
	log.Fatal(err)
}

embeddings, err := json.MarshalIndent(result.Embeddings, "", "  ")
if err != nil {
	log.Fatal(err)
}
fmt.Println(string(embeddings))

Muszla

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:batchEmbedContents" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"requests": [{
      "model": "models/gemini-embedding-001",
      "content": {
      "parts":[{
        "text": "What is the meaning of life?"}]}, },
      {
      "model": "models/gemini-embedding-001",
      "content": {
      "parts":[{
        "text": "How much wood would a woodchuck chuck?"}]}, },
      {
      "model": "models/gemini-embedding-001",
      "content": {
      "parts":[{
        "text": "How does the brain work?"}]}, }, ]}' 2> /dev/null | grep -C 5 values

Treść odpowiedzi

Odpowiedź na BatchEmbedContentsRequest.

W przypadku powodzenia treść żądania zawiera dane o następującej strukturze:

Pola
embeddings[] object (ContentEmbedding)

Tylko dane wyjściowe. Osadzanie dla każdego żądania w tej samej kolejności, w jakiej zostało podane w żądaniu zbiorczym.

Zapis JSON
{
  "embeddings": [
    {
      object (ContentEmbedding)
    }
  ]
}

Metoda: models.asyncBatchEmbedContent

Dodaje do kolejki partię models.embedContent żądań do przetwarzania wsadowego. Mamy moduł obsługi models.batchEmbedContentsGenerativeService, ale został on zsynchronizowany. Aby uniknąć nieporozumień, nazwiemy go Async.

Punkt końcowy

post https://generativelanguage.googleapis.com/v1beta/{batch.model=models/*}:asyncBatchEmbedContent

Parametry ścieżki

batch.model string

Wymagane. Nazwa Model, która ma być użyta do wygenerowania dokończenia.

Format: models/{model}. Ma on postać models/{model}.

Treść żądania

Treść żądania zawiera dane o następującej strukturze:

Pola
batch.name string

Tylko dane wyjściowe. Identyfikator. Nazwa zasobu pakietu.

Format: batches/{batchId}.

batch.displayName string

Wymagane. Nazwa tego pakietu zdefiniowana przez użytkownika.

batch.inputConfig object (InputEmbedContentConfig)

Wymagane. Konfiguracja wejściowa instancji, na których wykonywane jest przetwarzanie wsadowe.

batch.output object (EmbedContentBatchOutput)

Tylko dane wyjściowe. Dane wyjściowe żądania zbiorczego.

batch.createTime string (Timestamp format)

Tylko dane wyjściowe. Czas utworzenia partii.

Korzysta ze standardu RFC 3339, w którym wygenerowane dane wyjściowe są zawsze znormalizowane do formatu Z i zawierają 0, 3, 6 lub 9 cyfr po przecinku. Akceptowane są też przesunięcia inne niż „Z”. Przykłady: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" lub "2014-10-02T15:01:23+05:30".

batch.endTime string (Timestamp format)

Tylko dane wyjściowe. Godzina zakończenia przetwarzania wsadowego.

Korzysta ze standardu RFC 3339, w którym wygenerowane dane wyjściowe są zawsze znormalizowane do formatu Z i zawierają 0, 3, 6 lub 9 cyfr po przecinku. Akceptowane są też przesunięcia inne niż „Z”. Przykłady: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" lub "2014-10-02T15:01:23+05:30".

batch.updateTime string (Timestamp format)

Tylko dane wyjściowe. Czas ostatniej aktualizacji pakietu.

Korzysta ze standardu RFC 3339, w którym wygenerowane dane wyjściowe są zawsze znormalizowane do formatu Z i zawierają 0, 3, 6 lub 9 cyfr po przecinku. Akceptowane są też przesunięcia inne niż „Z”. Przykłady: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" lub "2014-10-02T15:01:23+05:30".

batch.batchStats object (EmbedContentBatchStats)

Tylko dane wyjściowe. Statystyki dotyczące partii.

batch.state enum (BatchState)

Tylko dane wyjściowe. Stan partii.

batch.priority string (int64 format)

Opcjonalnie. Priorytet zadania wsadowego. Partie o wyższej wartości priorytetu będą przetwarzane przed partiami o niższej wartości priorytetu. Dozwolone są wartości ujemne. Wartość domyślna to 0.

Treść odpowiedzi

W przypadku powodzenia treść odpowiedzi obejmuje wystąpienie elementu Operation.

EmbedContentRequest

Żądanie zawierające element Content, który model ma osadzić.

Pola
model string

Wymagane. Nazwa zasobu modelu. Służy on jako identyfikator modelu.

Ta nazwa powinna pasować do nazwy modelu zwróconej przez metodę models.list.

Format: models/{model}

content object (Content)

Wymagane. Treści do umieszczenia. Zostaną zliczone tylko pola parts.text.

taskType enum (TaskType)

Opcjonalnie. Opcjonalny typ zadania, do którego będą używane wektory. Nieobsługiwane w starszych modelach (models/embedding-001).

title string

Opcjonalnie. Opcjonalny tytuł tekstu. Ma zastosowanie tylko wtedy, gdy TaskType to RETRIEVAL_DOCUMENT.

Uwaga: określenie wartości title dla parametru RETRIEVAL_DOCUMENT zapewnia lepszą jakość osadzania na potrzeby wyszukiwania.

outputDimensionality integer

Opcjonalnie. Opcjonalny zredukowany wymiar wyjściowego wektora dystrybucyjnego. Jeśli ta opcja jest ustawiona, nadmierne wartości w osadzaniu wyjściowym są obcinane od końca. Obsługiwane tylko przez nowsze modele od 2024 r. Jeśli używasz starszego modelu (models/embedding-001), nie możesz ustawić tej wartości.

Zapis JSON
{
  "model": string,
  "content": {
    object (Content)
  },
  "taskType": enum (TaskType),
  "title": string,
  "outputDimensionality": integer
}

EmbedContentResponse

Odpowiedź na EmbedContentRequest.

Pola
embedding object (ContentEmbedding)

Tylko dane wyjściowe. Wektor wygenerowany na podstawie treści wejściowych.

Zapis JSON
{
  "embedding": {
    object (ContentEmbedding)
  }
}

ContentEmbedding

Lista liczb zmiennoprzecinkowych reprezentujących osadzenie.

Pola
values[] number

Wartości wektora dystrybucyjnego.

Zapis JSON
{
  "values": [
    number
  ]
}

TaskType

Typ zadania, do którego będzie używane osadzanie.

Wartości w polu enum
TASK_TYPE_UNSPECIFIED Nieokreślona wartość, która domyślnie będzie jedną z pozostałych wartości wyliczeniowych.
RETRIEVAL_QUERY Określa, że podany tekst jest zapytaniem w ustawieniu wyszukiwania lub pobierania.
RETRIEVAL_DOCUMENT Określa, że podany tekst jest dokumentem z przeszukiwanego korpusu.
SEMANTIC_SIMILARITY Określa, że podany tekst będzie używany w przypadku STS.
CLASSIFICATION Określa, że podany tekst zostanie sklasyfikowany.
CLUSTERING Określa, że wektory dystrybucyjne będą używane do klastrowania.
QUESTION_ANSWERING Określa, że podany tekst będzie używany do odpowiadania na pytania.
FACT_VERIFICATION Określa, że podany tekst będzie używany do weryfikacji faktów.
CODE_RETRIEVAL_QUERY Określa, że podany tekst będzie używany do pobierania kodu.

EmbedContentBatch

Zasób reprezentujący partię żądań EmbedContent.

Pola
model string

Wymagane. Nazwa Model, która ma być użyta do wygenerowania dokończenia.

Format: models/{model}.

name string

Tylko dane wyjściowe. Identyfikator. Nazwa zasobu pakietu.

Format: batches/{batchId}.

displayName string

Wymagane. Nazwa tego pakietu zdefiniowana przez użytkownika.

inputConfig object (InputEmbedContentConfig)

Wymagane. Konfiguracja wejściowa instancji, na których wykonywane jest przetwarzanie wsadowe.

output object (EmbedContentBatchOutput)

Tylko dane wyjściowe. Dane wyjściowe żądania zbiorczego.

createTime string (Timestamp format)

Tylko dane wyjściowe. Czas utworzenia partii.

Korzysta ze standardu RFC 3339, w którym wygenerowane dane wyjściowe są zawsze znormalizowane do formatu Z i zawierają 0, 3, 6 lub 9 cyfr po przecinku. Akceptowane są też przesunięcia inne niż „Z”. Przykłady: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" lub "2014-10-02T15:01:23+05:30".

endTime string (Timestamp format)

Tylko dane wyjściowe. Godzina zakończenia przetwarzania wsadowego.

Korzysta ze standardu RFC 3339, w którym wygenerowane dane wyjściowe są zawsze znormalizowane do formatu Z i zawierają 0, 3, 6 lub 9 cyfr po przecinku. Akceptowane są też przesunięcia inne niż „Z”. Przykłady: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" lub "2014-10-02T15:01:23+05:30".

updateTime string (Timestamp format)

Tylko dane wyjściowe. Czas ostatniej aktualizacji pakietu.

Korzysta ze standardu RFC 3339, w którym wygenerowane dane wyjściowe są zawsze znormalizowane do formatu Z i zawierają 0, 3, 6 lub 9 cyfr po przecinku. Akceptowane są też przesunięcia inne niż „Z”. Przykłady: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" lub "2014-10-02T15:01:23+05:30".

batchStats object (EmbedContentBatchStats)

Tylko dane wyjściowe. Statystyki dotyczące partii.

state enum (BatchState)

Tylko dane wyjściowe. Stan partii.

priority string (int64 format)

Opcjonalnie. Priorytet zadania wsadowego. Partie o wyższej wartości priorytetu będą przetwarzane przed partiami o niższej wartości priorytetu. Dozwolone są wartości ujemne. Wartość domyślna to 0.

Zapis JSON
{
  "model": string,
  "name": string,
  "displayName": string,
  "inputConfig": {
    object (InputEmbedContentConfig)
  },
  "output": {
    object (EmbedContentBatchOutput)
  },
  "createTime": string,
  "endTime": string,
  "updateTime": string,
  "batchStats": {
    object (EmbedContentBatchStats)
  },
  "state": enum (BatchState),
  "priority": string
}

InputEmbedContentConfig

Konfiguruje dane wejściowe żądania zbiorczego.

Pola
source Union type
Wymagane. Źródło danych wejściowych. Pole source może mieć tylko jedną z tych wartości:
fileName string

Nazwa File zawierającego żądania wejściowe.

requests object (InlinedEmbedContentRequests)

Żądania do przetworzenia w partii.

Zapis JSON
{

  // source
  "fileName": string,
  "requests": {
    object (InlinedEmbedContentRequests)
  }
  // Union type
}

InlinedEmbedContentRequests

Żądania, które mają być przetwarzane w ramach pakietu, jeśli zostały podane w żądaniu utworzenia pakietu.

Pola
requests[] object (InlinedEmbedContentRequest)

Wymagane. Żądania do przetworzenia w partii.

Zapis JSON
{
  "requests": [
    {
      object (InlinedEmbedContentRequest)
    }
  ]
}

InlinedEmbedContentRequest

Żądanie do przetworzenia w ramach pakietu.

Pola
request object (EmbedContentRequest)

Wymagane. Żądanie do przetworzenia w ramach pakietu.

metadata object (Struct format)

Opcjonalnie. Metadane, które mają być powiązane z żądaniem.

Zapis JSON
{
  "request": {
    object (EmbedContentRequest)
  },
  "metadata": {
    object
  }
}

EmbedContentBatchOutput

Dane wyjściowe żądania zbiorczego. Jest on zwracany w polu AsyncBatchEmbedContentResponse lub EmbedContentBatch.output.

Pola
output Union type
Dane wyjściowe żądania zbiorczego. Pole output może mieć tylko jedną z tych wartości:
responsesFile string

Tylko dane wyjściowe. Identyfikator pliku zawierającego odpowiedzi. Plik będzie miał format JSONL i będzie zawierać po jednej odpowiedzi w wierszu. Odpowiedzi będą miały postać komunikatów EmbedContentResponse w formacie JSON. Odpowiedzi będą zapisywane w tej samej kolejności co żądania wejściowe.

inlinedResponses object (InlinedEmbedContentResponses)

Tylko dane wyjściowe. Odpowiedzi na żądania w pakiecie. Zwracany, gdy pakiet został utworzony przy użyciu żądań wbudowanych. Odpowiedzi będą w tej samej kolejności co żądania wejściowe.

Zapis JSON
{

  // output
  "responsesFile": string,
  "inlinedResponses": {
    object (InlinedEmbedContentResponses)
  }
  // Union type
}

InlinedEmbedContentResponses

Odpowiedzi na żądania w pakiecie.

Pola
inlinedResponses[] object (InlinedEmbedContentResponse)

Tylko dane wyjściowe. Odpowiedzi na żądania w pakiecie.

Zapis JSON
{
  "inlinedResponses": [
    {
      object (InlinedEmbedContentResponse)
    }
  ]
}

InlinedEmbedContentResponse

Odpowiedź na pojedyncze żądanie w pakiecie.

Pola
metadata object (Struct format)

Tylko dane wyjściowe. Metadane powiązane z żądaniem.

output Union type
Wynik żądania. Pole output może mieć tylko jedną z tych wartości:
error object (Status)

Tylko dane wyjściowe. Błąd, który wystąpił podczas przetwarzania żądania.

response object (EmbedContentResponse)

Tylko dane wyjściowe. Odpowiedź na prośbę.

Zapis JSON
{
  "metadata": {
    object
  },

  // output
  "error": {
    object (Status)
  },
  "response": {
    object (EmbedContentResponse)
  }
  // Union type
}

EmbedContentBatchStats

Statystyki dotyczące partii.

Pola
requestCount string (int64 format)

Tylko dane wyjściowe. Liczba żądań w partii.

successfulRequestCount string (int64 format)

Tylko dane wyjściowe. Liczba żądań, które zostały przetworzone.

failedRequestCount string (int64 format)

Tylko dane wyjściowe. Liczba żądań, których nie udało się przetworzyć.

pendingRequestCount string (int64 format)

Tylko dane wyjściowe. Liczba żądań, które nadal oczekują na przetworzenie.

Zapis JSON
{
  "requestCount": string,
  "successfulRequestCount": string,
  "failedRequestCount": string,
  "pendingRequestCount": string
}