Добро пожаловать в поиск векторного сходства Firebase Data Connect — реализацию семантического поиска Firebase, которая интегрируется с Google Vertex AI .
В основе этой функции лежат векторные вложения, представляющие собой массивы чисел с плавающей точкой, представляющие семантическое значение текста или медиафайлов. Выполняя поиск ближайшего соседа с использованием входного векторного вложения, можно найти весь семантически схожий контент. Data Connect использует для этой возможности расширение PostgreSQL pgvector
.
Этот мощный семантический поиск может быть полезен, например, для рекомендательных и поисковых систем. Он также является ключевым компонентом генерации данных с дополненной поисковой обработкой в генеративных ИИ-процессах. Документация по Vertex AI — отличное место для получения дополнительной информации .
Вы можете положиться на встроенную поддержку Data Connect для автоматического создания векторных вложений с помощью API вложений Vertex AI или использовать этот API для их создания вручную.
Предпосылки
Настройте Data Connect для вашего проекта.
Включить API Vertex AI .
Настраивать
Вы можете выбрать локальный поток разработки (для веб-разработчиков, разработчиков приложений на Kotlin для Android или iOS) или поток IDX (для веб-разработчиков). Для разработки можно использовать локальную базу данных или ваш рабочий проект Data Connect и его экземпляр Cloud SQL для PostgreSQL.
В данных инструкциях предполагается, что вы создали свой проект Data Connect следуя краткому руководству .
Интеграция с локальной PostgreSQL
- Настройте локальный экземпляр PostgreSQL.
- Назначьте себе роль IAM пользователя Vertex AI .
- Настройте учетные данные по умолчанию для приложения Google Cloud в своей среде.
- Установите расширение
pgvector
в локальный экземпляр PostgreSQL. - Включите расширение с помощью
CREATE EXTENSION vector
согласно инструкциям репозиторияpgvector
.
Интеграция с IDX
- Настройте рабочее пространство IDX с помощью шаблона Data Connect.
- Назначьте себе роль IAM пользователя Vertex AI .
- Включите расширение с помощью
CREATE EXTENSION vector
согласно инструкциям репозиторияpgvector
.
Разработайте свою схему
Для поиска векторных изображений добавьте в схему новое поле типа Vector
. Например, если вы хотите выполнить семантический поиск по описаниям фильмов, добавьте поле для хранения векторных векторных представлений, связанных с описанием фильма. В этой схеме добавлено поле descriptionEmbedding
для хранения векторных представлений для поля description
.
type Movie @table {
id: ID! @col(name: "movie_id") @default(id: ID! @col(name: "movie_id") @default(expr: "uuidV4()")
title: String!
description: String
descriptionEmbedding: Vector! @col(size:768)
// ...
}
Генерация и извлечение вложений
Data Connect обеспечивает интегрированную поддержку векторных вложений с помощью параметра _embed
server. Это указывает Data Connect на необходимость генерировать векторные вложения путём внутреннего вызова API вложения Vertex AI. Параметр _embed
server можно использовать как в мутациях, так и в запросах.
Мутации
Создание и сохранение вложений через Data Connect
В вашем приложении поиска векторных изображений вы, вероятно, захотите запросить генерацию вложений сразу после добавления записей в базу данных. Вот мутация createMovie
, которая добавляет запись о фильме в таблицу Movie
и передаёт описание фильма с указанной model
вложения.
mutation createMovie($movieData: Movie_Data! @pick(fields: ["title", "genre", "description"])) {
movie_insert(data: {
...movieData,
descriptionEmbedding_embed: {model: "textembedding-gecko@003", text: $movieData.description}
})
}
В некоторых случаях вам может потребоваться обновить описание и вставку фильма.
mutation updateDescription($id: String!, $description: String!) {
movie_update(id: $id, data: {
description: $description,
descriptionEmbedding_embed: {model: "textembedding-gecko@003", text: $description}
})
}
Чтобы вызвать последнюю мутацию из клиента:
import { updateMovieDescriptionWithEmbed } from 'lib/dataconnect-sdk/';
await updateMovieDescriptionWithEmbed({ id: movieId, description: description});
// Use the response
Запросы
Получите векторные вложения с помощью запроса, подобного следующему. Обратите внимание, что возвращаемое запросом descriptionEmbedding
представляет собой массив чисел с плавающей точкой, который обычно не читается человеком. Поэтому SDK, созданные Data Connect не поддерживают его прямой возврат.
Вы можете использовать возвращенные векторные вложения для поиска сходства, как описано в следующем разделе.
query getMovieDescription($id: String!) @auth(is: PUBLIC) {
movie(id: $id)
id
description
descriptionEmbedding
}
Выполнить поиск сходства
Теперь мы можем выполнить поиск по сходству.
Для каждого поля Vector
Data Connect генерирует функцию GraphQL, реализующую поиск по сходству. Имя этой функции — ${pluralType}_${vectorFieldName}_similarity
. Она поддерживает несколько параметров, как показано в следующих примерах и в списке литературы .
Вы можете определить функцию GraphQL, которая вызывает поиск по сходству. Как упоминалось выше, серверное значение _embed
предписывает Data Connect генерировать векторные эмбеддинги с помощью API-интерфейсов Vertex AI для эмбеддинга, в данном случае для создания эмбеддингов для поисковой строки, используемой для сравнения с эмбеддингами описаний фильмов.
В этом примере поиск по сходству вернёт до 5 фильмов, описание которых семантически наиболее близко к входному запросу. Набор результатов сортируется по возрастанию расстояния — от самого близкого к самому дальнему.
query searchMovieDescriptionUsingL2Similarity ($query: String!) @auth(level: PUBLIC) {
movies_descriptionEmbedding_similarity(
compare_embed: {model: "textembedding-gecko@003", text: $query},
where: {content: {ne: "No info available for this movie."}}, limit: 5)
{
id
title
description
}
}
Настройте запрос на сходство
Значения по умолчанию для параметров поиска, таких как method
и within
, хорошо подходят для большинства случаев. Однако, если вы заметили, что результаты вашего запроса слишком разнородны или отсутствуют нужные вам результаты, попробуйте настроить эти параметры.
Чтобы найти подходящее значение для within
, можно добавить _metadata.distance
к выбранным полям, чтобы увидеть, насколько далеко от вектора запроса находится каждый результат. На основе возвращаемых значений distance
можно задать параметр within
; будут включены только результаты с расстоянием меньше значения within
:
query searchMovieDescriptionUsingL2Similarity ($query: String!) @auth(level: PUBLIC) {
movies_descriptionEmbedding_similarity(
compare_embed: {model: "textembedding-gecko@003", text: $query},
within: 2,
where: {content: {ne: "No info available for this movie."}}, limit: 5)
{
id
title
description
_metadata {
distance
}
}
}
Вы также можете экспериментировать с различными функциями расстояния, устанавливая параметр method
.
query searchMovieDescriptionUsingL2Similarity ($query: String!) @auth(level: PUBLIC) {
movies_descriptionEmbedding_similarity(
compare_embed: {model: "textembedding-gecko@003", text: $query},
within: .5,
method: COSINE,
where: {content: {ne: "No info available for this movie."}}, limit: 5)
{
id
title
description
_metadata {
distance
}
}
}
Обратите внимание, что разные методы возвращают совершенно разные значения расстояния: если вы установили within
, вам нужно будет снова настроить это значение после изменения method
.
Вызовите запрос на сходство
Чтобы вызвать поиск по сходству из клиентского кода:
import { searchMovieDescriptionUsingL2similarity} from 'lib/dataconnect-sdk';
const response = await searchMovieDescriptionUsingL2similarity({ query });
// Use the response
Используйте пользовательские вставки
Data Connect также позволяет работать с встраиваниями напрямую как с Vector
, а не использовать значение сервера _embed
для их генерации.
Сохраните пользовательское встраивание
Используя API Vertex Embeddings, укажите соответствующую модель и запросите результаты встраивания правильного измерения.
Затем преобразуйте возвращенный массив чисел с плавающей точкой в Vector
, чтобы передать его в операцию обновления для хранения.
mutation updateDescription($id: String!, $description: String!, $descriptionEmbedding: Vector!) {
movie_update(id: $id, data: {
// title, genre...
description: $description,
descriptionEmbedding: $descriptionEmbedding
})
}
Выполнять поиск схожести с использованием пользовательских встраиваний
Выполните ту же операцию, чтобы извлечь вложения для поисковых терминов и преобразовать их в Vectors
.
Затем вызовите запрос _similarity
для выполнения каждого поиска.
query searchMovieDescriptionUsingL2Similarity($compare: Vector!, $within: Float, $excludesContent: String, $limit: Int) @auth(level: PUBLIC) {
movies_descriptionEmbedding_similarity(
compare: $compare,
method: L2,
within: $within,
where: {content: {ne: $excludesContent}}, limit: $limit)
{
id
title
description
}
}
Развертывание в производство
Разверните вашу схему и соединитель
Последним шагом в типичной итерации Data Connect является развертывание ваших активов в производстве.
При развертывании схемы, содержащей типы Vector
, в CloudSQL с помощью команды firebase deploy
, Firebase CLI выполняет необходимые шаги для включения генерации встраиваний на основе Vertex AI в вашем экземпляре CloudSQL.
firebase deploy --only dataconnect
Если вы хотите вручную включить поддержку встраивания в свой экземпляр CloudSQL или столкнулись с ошибкой CLI, следуйте этим инструкциям .
Синтаксис поиска векторов
Расширения схемы
Тип данных Vector
в Data Connect соответствует vector
типу PostgreSQL, определенному расширением pgvector
. vector
тип pgvector хранится в PostgreSQL как массив чисел с плавающей запятой одинарной точности.
В Data Connect тип Vector
представлен как массив чисел JSON. Входные данные преобразуются в массив значений float32
. Если преобразование не удалось, возникает ошибка.
Используйте параметр size директивы @col
для задания размеров вектора.
type Question @table {
text: String!
category: String!
textEmbedding: Vector! @col(size: 768)
}
size
поддерживается только для Vector
типов. Vector
операции, такие как поиск по сходству, требуют, чтобы все Vector
имели одинаковое количество измерений.
directive @col(
# … existing args
"""
Defines a fixed column size for certain scalar types.
- For Vector, size is required.
- For all other types, size is currently unsupported and hence supplying it will result in a schema error.
"""
size: Int
) on FIELD_DEFINITION
_embed
значение сервера для запросов и мутаций
_embed
Это серверное значение указывает службе Data Connect на необходимость генерировать и хранить вложения с помощью API встраивания Vertex AI . Это серверное значение можно использовать как в запросах, так и в мутациях.
Параметры поиска по сходству
method: COSINE|INNER_PRODUCT|L2
Функция расстояния, используемая для поиска ближайших соседей. Поддерживаемые в настоящее время алгоритмы являются подмножеством алгоритмов поиска pgvector .
within: float
Ограничение на расстояние, в пределах которого выполняется поиск ближайшего соседа.
where: FDC filter condition
См. руководство по схемам, запросам и мутациям .
limit: int
Количество возвращаемых результатов.
,Добро пожаловать в поиск векторного сходства Firebase Data Connect — реализацию семантического поиска Firebase, которая интегрируется с Google Vertex AI .
В основе этой функции лежат векторные вложения, представляющие собой массивы чисел с плавающей точкой, представляющие семантическое значение текста или медиафайлов. Выполняя поиск ближайшего соседа с использованием входного векторного вложения, можно найти весь семантически схожий контент. Data Connect использует для этой возможности расширение PostgreSQL pgvector
.
Этот мощный семантический поиск может быть полезен, например, для рекомендательных и поисковых систем. Он также является ключевым компонентом генерации данных с дополненной поисковой обработкой в генеративных ИИ-процессах. Документация по Vertex AI — отличное место для получения дополнительной информации .
Вы можете положиться на встроенную поддержку Data Connect для автоматического создания векторных вложений с помощью API вложений Vertex AI или использовать этот API для их создания вручную.
Предпосылки
Настройте Data Connect для вашего проекта.
Включить API Vertex AI .
Настраивать
Вы можете выбрать локальный поток разработки (для веб-разработчиков, разработчиков приложений на Kotlin для Android или iOS) или поток IDX (для веб-разработчиков). Для разработки можно использовать локальную базу данных или ваш рабочий проект Data Connect и его экземпляр Cloud SQL для PostgreSQL.
В данных инструкциях предполагается, что вы создали свой проект Data Connect следуя краткому руководству .
Интеграция с локальной PostgreSQL
- Настройте локальный экземпляр PostgreSQL.
- Назначьте себе роль IAM пользователя Vertex AI .
- Настройте учетные данные по умолчанию для приложения Google Cloud в своей среде.
- Установите расширение
pgvector
в локальный экземпляр PostgreSQL. - Включите расширение с помощью
CREATE EXTENSION vector
согласно инструкциям репозиторияpgvector
.
Интеграция с IDX
- Настройте рабочее пространство IDX с помощью шаблона Data Connect.
- Назначьте себе роль IAM пользователя Vertex AI .
- Включите расширение с помощью
CREATE EXTENSION vector
согласно инструкциям репозиторияpgvector
.
Разработайте свою схему
Для поиска векторных изображений добавьте в схему новое поле типа Vector
. Например, если вы хотите выполнить семантический поиск по описаниям фильмов, добавьте поле для хранения векторных векторных представлений, связанных с описанием фильма. В этой схеме добавлено поле descriptionEmbedding
для хранения векторных представлений для поля description
.
type Movie @table {
id: ID! @col(name: "movie_id") @default(id: ID! @col(name: "movie_id") @default(expr: "uuidV4()")
title: String!
description: String
descriptionEmbedding: Vector! @col(size:768)
// ...
}
Генерация и извлечение вложений
Data Connect обеспечивает интегрированную поддержку векторных вложений с помощью параметра _embed
server. Это указывает Data Connect на необходимость генерировать векторные вложения путём внутреннего вызова API вложения Vertex AI. Параметр _embed
server можно использовать как в мутациях, так и в запросах.
Мутации
Создание и сохранение вложений через Data Connect
В вашем приложении поиска векторных изображений вы, вероятно, захотите запросить генерацию вложений сразу после добавления записей в базу данных. Вот мутация createMovie
, которая добавляет запись о фильме в таблицу Movie
и передаёт описание фильма с указанной model
вложения.
mutation createMovie($movieData: Movie_Data! @pick(fields: ["title", "genre", "description"])) {
movie_insert(data: {
...movieData,
descriptionEmbedding_embed: {model: "textembedding-gecko@003", text: $movieData.description}
})
}
В некоторых случаях вам может потребоваться обновить описание и вставку фильма.
mutation updateDescription($id: String!, $description: String!) {
movie_update(id: $id, data: {
description: $description,
descriptionEmbedding_embed: {model: "textembedding-gecko@003", text: $description}
})
}
Чтобы вызвать последнюю мутацию из клиента:
import { updateMovieDescriptionWithEmbed } from 'lib/dataconnect-sdk/';
await updateMovieDescriptionWithEmbed({ id: movieId, description: description});
// Use the response
Запросы
Получите векторные вложения с помощью запроса, подобного следующему. Обратите внимание, что возвращаемое запросом descriptionEmbedding
представляет собой массив чисел с плавающей точкой, который обычно не читается человеком. Поэтому SDK, созданные Data Connect не поддерживают его прямой возврат.
Вы можете использовать возвращенные векторные вложения для поиска сходства, как описано в следующем разделе.
query getMovieDescription($id: String!) @auth(is: PUBLIC) {
movie(id: $id)
id
description
descriptionEmbedding
}
Выполнить поиск сходства
Теперь мы можем выполнить поиск по сходству.
Для каждого поля Vector
Data Connect генерирует функцию GraphQL, реализующую поиск по сходству. Имя этой функции — ${pluralType}_${vectorFieldName}_similarity
. Она поддерживает несколько параметров, как показано в следующих примерах и в списке литературы .
Вы можете определить функцию GraphQL, которая вызывает поиск по сходству. Как упоминалось выше, серверное значение _embed
предписывает Data Connect генерировать векторные эмбеддинги с помощью API-интерфейсов Vertex AI для эмбеддинга, в данном случае для создания эмбеддингов для поисковой строки, используемой для сравнения с эмбеддингами описаний фильмов.
В этом примере поиск по сходству вернёт до 5 фильмов, описание которых семантически наиболее близко к входному запросу. Набор результатов сортируется по возрастанию расстояния — от самого близкого к самому дальнему.
query searchMovieDescriptionUsingL2Similarity ($query: String!) @auth(level: PUBLIC) {
movies_descriptionEmbedding_similarity(
compare_embed: {model: "textembedding-gecko@003", text: $query},
where: {content: {ne: "No info available for this movie."}}, limit: 5)
{
id
title
description
}
}
Настройте запрос на сходство
Значения по умолчанию для параметров поиска, таких как method
и within
, хорошо подходят для большинства случаев. Однако, если вы заметили, что результаты вашего запроса слишком разнородны или отсутствуют нужные вам результаты, попробуйте настроить эти параметры.
Чтобы найти подходящее значение для within
, можно добавить _metadata.distance
к выбранным полям, чтобы увидеть, насколько далеко от вектора запроса находится каждый результат. На основе возвращаемых значений distance
можно задать параметр within
; будут включены только результаты с расстоянием меньше значения within
:
query searchMovieDescriptionUsingL2Similarity ($query: String!) @auth(level: PUBLIC) {
movies_descriptionEmbedding_similarity(
compare_embed: {model: "textembedding-gecko@003", text: $query},
within: 2,
where: {content: {ne: "No info available for this movie."}}, limit: 5)
{
id
title
description
_metadata {
distance
}
}
}
Вы также можете экспериментировать с различными функциями расстояния, устанавливая параметр method
.
query searchMovieDescriptionUsingL2Similarity ($query: String!) @auth(level: PUBLIC) {
movies_descriptionEmbedding_similarity(
compare_embed: {model: "textembedding-gecko@003", text: $query},
within: .5,
method: COSINE,
where: {content: {ne: "No info available for this movie."}}, limit: 5)
{
id
title
description
_metadata {
distance
}
}
}
Обратите внимание, что разные методы возвращают совершенно разные значения расстояния: если вы установили within
, вам нужно будет снова настроить это значение после изменения method
.
Вызовите запрос на сходство
Чтобы вызвать поиск по сходству из клиентского кода:
import { searchMovieDescriptionUsingL2similarity} from 'lib/dataconnect-sdk';
const response = await searchMovieDescriptionUsingL2similarity({ query });
// Use the response
Используйте пользовательские вставки
Data Connect также позволяет работать с встраиваниями напрямую как с Vector
, а не использовать значение сервера _embed
для их генерации.
Сохраните пользовательское встраивание
Используя API Vertex Embeddings, укажите соответствующую модель и запросите результаты встраивания правильного измерения.
Затем преобразуйте возвращенный массив чисел с плавающей точкой в Vector
, чтобы передать его в операцию обновления для хранения.
mutation updateDescription($id: String!, $description: String!, $descriptionEmbedding: Vector!) {
movie_update(id: $id, data: {
// title, genre...
description: $description,
descriptionEmbedding: $descriptionEmbedding
})
}
Выполнять поиск схожести с использованием пользовательских встраиваний
Выполните ту же операцию, чтобы извлечь вложения для поисковых терминов и преобразовать их в Vectors
.
Затем вызовите запрос _similarity
для выполнения каждого поиска.
query searchMovieDescriptionUsingL2Similarity($compare: Vector!, $within: Float, $excludesContent: String, $limit: Int) @auth(level: PUBLIC) {
movies_descriptionEmbedding_similarity(
compare: $compare,
method: L2,
within: $within,
where: {content: {ne: $excludesContent}}, limit: $limit)
{
id
title
description
}
}
Развертывание в производство
Разверните вашу схему и соединитель
Последним шагом в типичной итерации Data Connect является развертывание ваших активов в производстве.
При развертывании схемы, содержащей типы Vector
, в CloudSQL с помощью команды firebase deploy
, Firebase CLI выполняет необходимые шаги для включения генерации встраиваний на основе Vertex AI в вашем экземпляре CloudSQL.
firebase deploy --only dataconnect
Если вы хотите вручную включить поддержку встраивания в свой экземпляр CloudSQL или столкнулись с ошибкой CLI, следуйте этим инструкциям .
Синтаксис поиска векторов
Расширения схемы
Тип данных Vector
в Data Connect соответствует vector
типу PostgreSQL, определенному расширением pgvector
. vector
тип pgvector хранится в PostgreSQL как массив чисел с плавающей запятой одинарной точности.
В Data Connect тип Vector
представлен как массив чисел JSON. Входные данные преобразуются в массив значений float32
. Если преобразование не удалось, возникает ошибка.
Используйте параметр size директивы @col
для задания размеров вектора.
type Question @table {
text: String!
category: String!
textEmbedding: Vector! @col(size: 768)
}
size
поддерживается только для Vector
типов. Vector
операции, такие как поиск по сходству, требуют, чтобы все Vector
имели одинаковое количество измерений.
directive @col(
# … existing args
"""
Defines a fixed column size for certain scalar types.
- For Vector, size is required.
- For all other types, size is currently unsupported and hence supplying it will result in a schema error.
"""
size: Int
) on FIELD_DEFINITION
_embed
значение сервера для запросов и мутаций
_embed
Это серверное значение указывает службе Data Connect на необходимость генерировать и хранить вложения с помощью API встраивания Vertex AI . Это серверное значение можно использовать как в запросах, так и в мутациях.
Параметры поиска по сходству
method: COSINE|INNER_PRODUCT|L2
Функция расстояния, используемая для поиска ближайших соседей. Поддерживаемые в настоящее время алгоритмы являются подмножеством алгоритмов поиска pgvector .
within: float
Ограничение на расстояние, в пределах которого выполняется поиск ближайшего соседа.
where: FDC filter condition
См. руководство по схемам, запросам и мутациям .
limit: int
Количество возвращаемых результатов.