Embeddings

Vectơ nhúng là một biểu diễn bằng số của dữ liệu đầu vào dạng văn bản, mở ra một số trường hợp sử dụng riêng biệt, chẳng hạn như phân cụm, đo lường mức độ tương đồng và truy xuất thông tin. Để xem phần giới thiệu, hãy tham khảo Hướng dẫn về việc nhúng.

Không giống như các mô hình AI tạo sinh tạo ra nội dung mới, mô hình Gemini Embedding chỉ nhằm mục đích chuyển đổi định dạng dữ liệu đầu vào của bạn thành một biểu diễn bằng số. Mặc dù Google chịu trách nhiệm cung cấp một mô hình nhúng giúp chuyển đổi định dạng dữ liệu đầu vào của bạn sang định dạng số theo yêu cầu, nhưng người dùng vẫn hoàn toàn chịu trách nhiệm về dữ liệu mà họ nhập và các vectơ nhúng thu được. Bằng việc sử dụng mô hình Nhúng Gemini, bạn xác nhận rằng bạn có các quyền cần thiết đối với mọi nội dung mình tải lên. Đừng tạo nội dung vi phạm quyền sở hữu trí tuệ hoặc quyền riêng tư của người khác. Khi sử dụng dịch vụ này, bạn phải tuân thủ Chính sách về các hành vi bị cấm khi sử dụngĐiều khoản dịch vụ của Google.

Phương thức: models.embedContent

Tạo một vectơ nhúng văn bản từ Content đầu vào bằng cách sử dụng mô hình Nhúng Gemini được chỉ định.

Điểm cuối

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

Tham số đường dẫn

model string

Bắt buộc. Tên tài nguyên của mô hình. Đây là mã nhận dạng mà Mô hình sẽ sử dụng.

Tên này phải khớp với tên mô hình do phương thức models.list trả về.

Định dạng: models/{model}. Định dạng này có dạng models/{model}.

Nội dung yêu cầu

Nội dung yêu cầu chứa dữ liệu có cấu trúc sau:

Trường
content object (Content)

Bắt buộc. Nội dung cần nhúng. Chỉ các trường parts.text mới được tính.

taskType enum (TaskType)

Không bắt buộc. Loại tác vụ không bắt buộc mà các mục nhúng sẽ được dùng. Không được hỗ trợ trên các mẫu cũ (models/embedding-001).

title string

Không bắt buộc. Tiêu đề không bắt buộc cho văn bản. Chỉ áp dụng khi TaskType là RETRIEVAL_DOCUMENT.

Lưu ý: Việc chỉ định một title cho RETRIEVAL_DOCUMENT sẽ cung cấp các mục nhúng có chất lượng tốt hơn để truy xuất.

outputDimensionality integer

Không bắt buộc. Phương diện giảm tuỳ chọn cho hoạt động nhúng đầu ra. Nếu được đặt, các giá trị dư thừa trong kết quả nhúng sẽ bị cắt bớt từ cuối. Chỉ được các mẫu mới hơn hỗ trợ từ năm 2024. Bạn không thể đặt giá trị này nếu đang dùng mô hình cũ (models/embedding-001).

Ví dụ về yêu cầu

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);

Go

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))

Vỏ

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?"}]}
    }'

Nội dung phản hồi

Nếu thành công, nội dung phản hồi sẽ chứa một phiên bản của EmbedContentResponse.

Phương thức: models.batchEmbedContents

Tạo nhiều vectơ nhúng từ Content đầu vào, bao gồm một loạt chuỗi được biểu thị dưới dạng các đối tượng EmbedContentRequest.

Điểm cuối

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

Tham số đường dẫn

model string

Bắt buộc. Tên tài nguyên của mô hình. Đây là mã nhận dạng mà Mô hình sẽ sử dụng.

Tên này phải khớp với tên mô hình do phương thức models.list trả về.

Định dạng: models/{model}. Định dạng này có dạng models/{model}.

Nội dung yêu cầu

Nội dung yêu cầu chứa dữ liệu có cấu trúc sau:

Trường
requests[] object (EmbedContentRequest)

Bắt buộc. Nhúng các yêu cầu cho lô. Mô hình trong mỗi yêu cầu này phải khớp với mô hình được chỉ định BatchEmbedContentsRequest.model.

Ví dụ về yêu cầu

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);

Go

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))

Vỏ

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

Nội dung phản hồi

Câu trả lời cho BatchEmbedContentsRequest.

Nếu thành công, phần nội dung phản hồi sẽ chứa dữ liệu có cấu trúc sau:

Trường
embeddings[] object (ContentEmbedding)

Chỉ có đầu ra. Các vectơ nhúng cho mỗi yêu cầu, theo cùng thứ tự như trong yêu cầu theo lô.

Biểu diễn dưới dạng JSON
{
  "embeddings": [
    {
      object (ContentEmbedding)
    }
  ]
}

Phương thức: models.asyncBatchEmbedContent

Đưa một loạt yêu cầu models.embedContent vào hàng đợi để xử lý hàng loạt. Chúng tôi có trình xử lý models.batchEmbedContents trong GenerativeService, nhưng trình xử lý này đã được đồng bộ hoá. Vì vậy, chúng ta đặt tên cho thành phần này là Async để tránh nhầm lẫn.

Điểm cuối

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

Tham số đường dẫn

batch.model string

Bắt buộc. Tên của Model dùng để tạo phần đề xuất hoàn thành.

Định dạng: models/{model}. Địa chỉ này có dạng models/{model}.

Nội dung yêu cầu

Nội dung yêu cầu chứa dữ liệu có cấu trúc sau:

Trường
batch.name string

Chỉ có đầu ra. Giá trị nhận dạng. Tên tài nguyên của lô.

Định dạng: batches/{batchId}.

batch.displayName string

Bắt buộc. Tên do người dùng xác định của lô này.

batch.inputConfig object (InputEmbedContentConfig)

Bắt buộc. Cấu hình đầu vào của các phiên bản mà quy trình xử lý hàng loạt được thực hiện.

batch.output object (EmbedContentBatchOutput)

Chỉ có đầu ra. Đầu ra của yêu cầu theo lô.

batch.createTime string (Timestamp format)

Chỉ có đầu ra. Thời gian tạo lô.

Sử dụng RFC 3339, trong đó đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các độ lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".

batch.endTime string (Timestamp format)

Chỉ có đầu ra. Thời điểm hoàn tất quy trình xử lý hàng loạt.

Sử dụng RFC 3339, trong đó đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các độ lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".

batch.updateTime string (Timestamp format)

Chỉ có đầu ra. Thời gian cập nhật gần đây nhất của lô.

Sử dụng RFC 3339, trong đó đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các độ lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".

batch.batchStats object (EmbedContentBatchStats)

Chỉ có đầu ra. Số liệu thống kê về lô.

batch.state enum (BatchState)

Chỉ có đầu ra. Trạng thái của lô.

batch.priority string (int64 format)

Không bắt buộc. Mức độ ưu tiên của lô. Các lô có giá trị ưu tiên cao hơn sẽ được xử lý trước các lô có giá trị ưu tiên thấp hơn. Bạn có thể dùng giá trị âm. Giá trị mặc định là 0.

Nội dung phản hồi

Nếu thành công, nội dung phản hồi sẽ chứa một phiên bản của Operation.

EmbedContentRequest

Yêu cầu chứa Content cho mô hình cần nhúng.

Trường
model string

Bắt buộc. Tên tài nguyên của mô hình. Đây là mã nhận dạng mà Mô hình sẽ sử dụng.

Tên này phải khớp với tên mô hình do phương thức models.list trả về.

Định dạng models/{model}

content object (Content)

Bắt buộc. Nội dung cần nhúng. Chỉ các trường parts.text mới được tính.

taskType enum (TaskType)

Không bắt buộc. Loại tác vụ không bắt buộc mà các mục nhúng sẽ được dùng. Không được hỗ trợ trên các mẫu cũ (models/embedding-001).

title string

Không bắt buộc. Tiêu đề không bắt buộc cho văn bản. Chỉ áp dụng khi TaskType là RETRIEVAL_DOCUMENT.

Lưu ý: Việc chỉ định một title cho RETRIEVAL_DOCUMENT sẽ cung cấp các mục nhúng có chất lượng tốt hơn để truy xuất.

outputDimensionality integer

Không bắt buộc. Phương diện giảm tuỳ chọn cho hoạt động nhúng đầu ra. Nếu được đặt, các giá trị dư thừa trong kết quả nhúng sẽ bị cắt bớt từ cuối. Chỉ được các mẫu mới hơn hỗ trợ từ năm 2024. Bạn không thể đặt giá trị này nếu đang dùng mô hình cũ (models/embedding-001).

Biểu diễn dưới dạng JSON
{
  "model": string,
  "content": {
    object (Content)
  },
  "taskType": enum (TaskType),
  "title": string,
  "outputDimensionality": integer
}

EmbedContentResponse

Câu trả lời cho EmbedContentRequest.

Trường
embedding object (ContentEmbedding)

Chỉ có đầu ra. Vectơ nhúng được tạo từ nội dung đầu vào.

Biểu diễn dưới dạng JSON
{
  "embedding": {
    object (ContentEmbedding)
  }
}

ContentEmbedding

Một danh sách các số dấu phẩy động biểu thị một vectơ nhúng.

Trường
values[] number

Các giá trị nhúng.

Biểu diễn dưới dạng JSON
{
  "values": [
    number
  ]
}

TaskType

Loại nhiệm vụ mà bạn sẽ dùng để nhúng.

Enum
TASK_TYPE_UNSPECIFIED Giá trị chưa đặt, sẽ mặc định là một trong các giá trị enum khác.
RETRIEVAL_QUERY Chỉ định văn bản đã cho là một truy vấn trong chế độ cài đặt tìm kiếm/truy xuất.
RETRIEVAL_DOCUMENT Chỉ định văn bản đã cho là một tài liệu trong kho ngữ liệu đang được tìm kiếm.
SEMANTIC_SIMILARITY Chỉ định văn bản đã cho sẽ được dùng cho STS.
CLASSIFICATION Chỉ định rằng văn bản đã cho sẽ được phân loại.
CLUSTERING Chỉ định rằng các mục nhúng sẽ được dùng để phân cụm.
QUESTION_ANSWERING Chỉ định rằng văn bản đã cho sẽ được dùng để trả lời câu hỏi.
FACT_VERIFICATION Chỉ định rằng văn bản đã cho sẽ được dùng để xác minh tính xác thực.
CODE_RETRIEVAL_QUERY Chỉ định rằng văn bản đã cho sẽ được dùng để truy xuất mã.

EmbedContentBatch

Một tài nguyên đại diện cho một nhóm yêu cầu EmbedContent.

Trường
model string

Bắt buộc. Tên của Model dùng để tạo phần đề xuất hoàn thành.

Định dạng: models/{model}.

name string

Chỉ có đầu ra. Giá trị nhận dạng. Tên tài nguyên của lô.

Định dạng: batches/{batchId}.

displayName string

Bắt buộc. Tên do người dùng xác định của lô này.

inputConfig object (InputEmbedContentConfig)

Bắt buộc. Cấu hình đầu vào của các phiên bản mà quy trình xử lý hàng loạt được thực hiện.

output object (EmbedContentBatchOutput)

Chỉ có đầu ra. Đầu ra của yêu cầu theo lô.

createTime string (Timestamp format)

Chỉ có đầu ra. Thời gian tạo lô.

Sử dụng RFC 3339, trong đó đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các độ lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".

endTime string (Timestamp format)

Chỉ có đầu ra. Thời điểm hoàn tất quy trình xử lý hàng loạt.

Sử dụng RFC 3339, trong đó đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các độ lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".

updateTime string (Timestamp format)

Chỉ có đầu ra. Thời gian cập nhật gần đây nhất của lô.

Sử dụng RFC 3339, trong đó đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các độ lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".

batchStats object (EmbedContentBatchStats)

Chỉ có đầu ra. Số liệu thống kê về lô.

state enum (BatchState)

Chỉ có đầu ra. Trạng thái của lô.

priority string (int64 format)

Không bắt buộc. Mức độ ưu tiên của lô. Các lô có giá trị ưu tiên cao hơn sẽ được xử lý trước các lô có giá trị ưu tiên thấp hơn. Bạn có thể dùng giá trị âm. Giá trị mặc định là 0.

Biểu diễn dưới dạng 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

Định cấu hình dữ liệu đầu vào cho yêu cầu hàng loạt.

Trường
source Union type
Bắt buộc. Nguồn của dữ liệu đầu vào. source chỉ có thể là một trong những trạng thái sau:
fileName string

Tên của File chứa các yêu cầu đầu vào.

requests object (InlinedEmbedContentRequests)

Các yêu cầu cần được xử lý trong lô.

Biểu diễn dưới dạng JSON
{

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

InlinedEmbedContentRequests

Các yêu cầu cần được xử lý theo lô nếu được cung cấp trong yêu cầu tạo lô.

Trường
requests[] object (InlinedEmbedContentRequest)

Bắt buộc. Các yêu cầu cần được xử lý trong lô.

Biểu diễn dưới dạng JSON
{
  "requests": [
    {
      object (InlinedEmbedContentRequest)
    }
  ]
}

InlinedEmbedContentRequest

Yêu cầu cần được xử lý trong lô.

Trường
request object (EmbedContentRequest)

Bắt buộc. Yêu cầu cần được xử lý trong lô.

metadata object (Struct format)

Không bắt buộc. Siêu dữ liệu sẽ được liên kết với yêu cầu.

Biểu diễn dưới dạng JSON
{
  "request": {
    object (EmbedContentRequest)
  },
  "metadata": {
    object
  }
}

EmbedContentBatchOutput

Đầu ra của một yêu cầu theo lô. Tham số này được trả về trong trường AsyncBatchEmbedContentResponse hoặc EmbedContentBatch.output.

Trường
output Union type
Đầu ra của yêu cầu theo lô. output chỉ có thể là một trong những trạng thái sau:
responsesFile string

Chỉ có đầu ra. Mã nhận dạng tệp của tệp chứa các câu trả lời. Tệp này sẽ là một tệp JSONL có một phản hồi trên mỗi dòng. Các phản hồi sẽ là thông báo EmbedContentResponse được định dạng dưới dạng JSON. Các câu trả lời sẽ được viết theo thứ tự giống như các yêu cầu đầu vào.

inlinedResponses object (InlinedEmbedContentResponses)

Chỉ có đầu ra. Các phản hồi cho các yêu cầu trong lô. Trả về khi lô được tạo bằng các yêu cầu nội tuyến. Các phản hồi sẽ theo cùng thứ tự với các yêu cầu đầu vào.

Biểu diễn dưới dạng JSON
{

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

InlinedEmbedContentResponses

Các phản hồi cho các yêu cầu trong lô.

Trường
inlinedResponses[] object (InlinedEmbedContentResponse)

Chỉ có đầu ra. Các phản hồi cho các yêu cầu trong lô.

Biểu diễn dưới dạng JSON
{
  "inlinedResponses": [
    {
      object (InlinedEmbedContentResponse)
    }
  ]
}

InlinedEmbedContentResponse

Phản hồi cho một yêu cầu trong lô.

Trường
metadata object (Struct format)

Chỉ có đầu ra. Siêu dữ liệu liên kết với yêu cầu.

output Union type
Kết quả của yêu cầu. output chỉ có thể là một trong những trạng thái sau:
error object (Status)

Chỉ có đầu ra. Đã xảy ra lỗi trong khi xử lý yêu cầu.

response object (EmbedContentResponse)

Chỉ có đầu ra. Phản hồi cho yêu cầu.

Biểu diễn dưới dạng JSON
{
  "metadata": {
    object
  },

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

EmbedContentBatchStats

Số liệu thống kê về lô.

Trường
requestCount string (int64 format)

Chỉ có đầu ra. Số lượng yêu cầu trong lô.

successfulRequestCount string (int64 format)

Chỉ có đầu ra. Số yêu cầu đã được xử lý thành công.

failedRequestCount string (int64 format)

Chỉ có đầu ra. Số lượng yêu cầu không xử lý được.

pendingRequestCount string (int64 format)

Chỉ có đầu ra. Số lượng yêu cầu vẫn đang chờ xử lý.

Biểu diễn dưới dạng JSON
{
  "requestCount": string,
  "successfulRequestCount": string,
  "failedRequestCount": string,
  "pendingRequestCount": string
}