Модуль google.cloud.gcp_vertexai_index — создание ресурса GCP VertexAI.Index

Примечание

Этот модуль входит в коллекцию google.cloud (версия 1.13.0).

Возможно, эта коллекция уже установлена, если вы используете пакет ansible. Она не входит в ansible-core. Чтобы проверить, установлена ли она, выполните ansible-galaxy collection list.

Для установки используйте: ansible-galaxy collection install google.cloud. Для использования этого модуля необходимы дополнительные требования. Подробности см. в разделе Требования.

Чтобы использовать модуль в плейбуке, укажите: google.cloud.gcp_vertexai_index.

Краткое описание
Требования
Параметры
Примечания
Примеры
Возвращаемые значения

Краткое описание

Представление коллекции элементов базы данных, организованных таким образом, чтобы можно было выполнять поиск с помощью алгоритмов приближённого поиска ближайших соседей (ANN).

Требования

На хосте, выполняющем этот модуль, должны быть установлены следующие компоненты.

python >= 3.8
requests >= 2.18.4
google-auth >= 2.25.1

Параметры

Параметр	Комментарии
access_token string	Токен доступа, используемый для аутентификации.
auth_kind string / обязательный	Тип используемых учётных данных. Варианты: `"accesstoken"` `"application"` `"machineaccount"` `"serviceaccount"`
description string	Описание индекса.
display_name string / обязательный	Отображаемое имя индекса. Имя может содержать до 128 символов и любые символы UTF-8.
encryption_spec dictionary	Спецификация ключа шифрования, управляемого клиентом, для индекса. Если задано, этот индекс и все его подресурсы будут защищены этим ключом.
kms_key_name string / обязательный	Идентификатор ресурса Cloud KMS для ключа шифрования, управляемого клиентом и используемого для защиты ресурса. Имеет вид: `projects/my-project/locations/my-region/keyRings/my-kr/cryptoKeys/my-key`. Ключ должен находиться в том же регионе, в котором создаётся вычислительный ресурс.
env_type string	Указывает, в какой среде Ansible выполняется этот модуль. Не задавайте этот параметр, если не знаете, что делаете. Этот параметр изменяет только строку User Agent для запросов к API.
index_update_method string	Метод обновления для этого индекса. Допустимы следующие значения. Если параметр не задан, по умолчанию используется BATCH_UPDATE. * BATCH_UPDATE: пользователь может вызвать indexes.patch, указав файлы с точками данных в Cloud Storage для обновления. * STREAM_UPDATE: пользователь может вызвать indexes.upsertDatapoints/DeleteDatapoints для обновления индекса; изменения будут применены к соответствующим DeployedIndexes практически в реальном времени. По умолчанию: `"BATCH_UPDATE"`
labels dictionary	Метки с определяемыми пользователем метаданными для упорядочивания индексов.
metadata dictionary / обязательный	Дополнительные сведения об индексе. Хотя в спецификации API это поле не отмечено как обязательное, в настоящее время оно требуется при создании индекса и должно быть указано. Попытка создать индекс без этого поля приведёт к ошибке API.
config dictionary / обязательный	Конфигурация индекса Matching Engine.
algorithm_config dictionary	Конфигурация алгоритмов, используемых для эффективного поиска. Это поле может требоваться в зависимости от вашей конфигурации.
brute_force_config dictionary	Параметры конфигурации для поиска полным перебором, который выполняет стандартный линейный поиск в базе данных для каждого запроса.
tree_ah_config dictionary	Параметры конфигурации для алгоритма tree-AH (неглубокое дерево + асимметричное хеширование). Подробнее см. в этой статье: https://arxiv.org/abs/1908.10396.
leaf_node_embedding_count integer	Количество эмбеддингов в каждом листовом узле. Если значение не задано, по умолчанию используется 1000. По умолчанию: `1000`
leaf_nodes_to_search_percent integer	Доля листовых узлов, в которых выполняется поиск по запросу, по умолчанию. Значение должно быть в диапазоне от 1 до 100 включительно. Если значение не задано, по умолчанию используется 10 (то есть 10%). По умолчанию: `10`
approximate_neighbors_count integer	Количество соседей, которые по умолчанию нужно найти с помощью приближённого поиска до выполнения точной сортировки. Точная сортировка — это процедура, в ходе которой результаты, возвращённые алгоритмом приближённого поиска, сортируются заново с помощью более ресурсоёмкого вычисления расстояния. Обязательный параметр при использовании алгоритма tree-AH.
dimensions integer / обязательный	Количество измерений входных векторов.
distance_measure_type string	Метрика расстояния, используемая при поиске ближайших соседей. Допустимы следующие значения: * SQUARED_L2_DISTANCE: евклидово расстояние (L_2) * L1_DISTANCE: манхэттенское расстояние (L_1) * COSINE_DISTANCE: косинусное расстояние. Определяется как 1 минус косинусное сходство. * DOT_PRODUCT_DISTANCE: расстояние по скалярному произведению. Определяется как отрицательное значение скалярного произведения. По умолчанию: `"DOT_PRODUCT_DISTANCE"`
feature_norm_type string	Тип нормализации, применяемой к каждому вектору. Допустимы следующие значения: * UNIT_L2_NORM: нормализация L2 до единичной длины * NONE: нормализация не задана. По умолчанию: `"NONE"`
shard_size string	Данные индекса делятся на равные части для обработки. Эти части называются «шардами». При создании индекса необходимо указать размер шарда. Допустимы следующие значения: * SHARD_SIZE_SMALL: малый (2 ГБ) * SHARD_SIZE_MEDIUM: средний (20 ГБ) * SHARD_SIZE_LARGE: большой (50 ГБ).
contents_delta_uri string	Позволяет добавлять, обновлять и удалять содержимое индекса Matching Engine. Строка должна содержать допустимый путь к каталогу Cloud Storage. Если это поле задано при вызове IndexService.UpdateIndex, то в рамках того же вызова нельзя обновить другие поля индекса. Ожидаемая структура и формат файлов, на которые указывает этот URI, описаны по адресу https://cloud.google.com/vertex-ai/docs/matching-engine/using-matching-engine#input-data-format.
is_complete_overwrite boolean	Если это поле задано вместе с contentsDeltaUri при вызове IndexService.UpdateIndex, существующее содержимое индекса будет заменено данными из contentsDeltaUri. Варианты: `false` ← (по умолчанию) `true`
project string	Проект Google Cloud Platform, который будет использоваться.
region string	Регион индекса. Например, us-central1.
scopes list / элементы=string	Массив используемых областей доступа.
service_account_contents jsonarg	Содержимое JSON-файла сервисного аккаунта, представленное в виде словаря или строки JSON.
service_account_email string	Необязательный адрес электронной почты сервисного аккаунта, если выбран machineaccount и пользователь не хочет использовать адрес по умолчанию.
service_account_file path	Путь к JSON-файлу сервисного аккаунта, если в качестве типа выбран serviceaccount.
state string	Должен ли ресурс существовать в GCP. Варианты: `"present"` ← (по умолчанию) `"absent"`

Примечания

Примечание

Справочник API: https://cloud.google.com/vertex-ai/docs/reference/rest/v1/projects.locations.indexes/
Для аутентификации можно задать auth_kind с помощью переменной среды GCP_AUTH_KIND.
Для аутентификации можно задать service_account_file с помощью переменной среды GCP_SERVICE_ACCOUNT_FILE.
Для аутентификации можно задать service_account_contents с помощью переменной среды GCP_SERVICE_ACCOUNT_CONTENTS.
Для аутентификации можно задать service_account_email с помощью переменной среды GCP_SERVICE_ACCOUNT_EMAIL.
Для аутентификации можно задать access_token с помощью переменной среды GCP_ACCESS_TOKEN.
Для аутентификации можно задать scopes с помощью переменной среды GCP_SCOPES.
Значения переменных среды используются только в том случае, если значения плейбука не заданы.
Параметры service_account_email, service_account_file, service_account_file и access_token являются взаимоисключающими.

Примеры

- name: Create Index
  google.cloud.gcp_vertexai_index:
    state: present
    display_name: "{{ resource_name }}"
    region: us-central1
    metadata:
      contents_delta_uri: "gs://{{ resource_name }}/contents"
      config:
        dimensions: 2
        approximate_neighbors_count: 150
        shard_size: SHARD_SIZE_SMALL
        distance_measure_type: DOT_PRODUCT_DISTANCE
        algorithm_config:
          tree_ah_config:
            leaf_node_embedding_count: 500
            leaf_nodes_to_search_percent: 7
    project: "{{ gcp_project }}"
    auth_kind: "{{ gcp_cred_kind }}"
    service_account_file: "{{ gcp_cred_file }}"

################################################################################

- name: Create Index with streaming updates
  google.cloud.gcp_vertexai_index:
    state: present
    display_name: "{{ resource_name }}"
    region: us-central1
    metadata:
      contents_delta_uri: "gs://{{ resource_name }}/contents"
      config:
        dimensions: 2
        shard_size: SHARD_SIZE_LARGE
        distance_measure_type: COSINE_DISTANCE
        feature_norm_type: UNIT_L2_NORM
        algorithm_config:
          brute_force_config: {}
    index_update_method: STREAM_UPDATE
    project: "{{ gcp_project }}"
    auth_kind: "{{ gcp_cred_kind }}"
    service_account_file: "{{ gcp_cred_file }}"

Возвращаемые значения

Общие возвращаемые значения описаны здесь. Ниже перечислены поля, уникальные для этого модуля:

Ключ	Описание
changed boolean	Был ли изменён ресурс. Возвращается: всегда
createTime string	Время создания индекса в формате RFC3339 UTC «Zulu», с точностью до наносекунд и максимум девятью знаками после запятой. Возвращается: при успешном выполнении
deployedIndexes list / элементы=dictionary	Ссылки на DeployedIndexes, созданные на основе этого индекса. Индекс можно удалить, только если сначала отменено развёртывание всех его DeployedIndexes. Возвращается: при успешном выполнении
deployedIndexId string	Идентификатор DeployedIndex в указанной выше IndexEndpoint. Возвращается: при успешном выполнении
indexEndpoint string	Имя ресурса IndexEndpoint. Возвращается: при успешном выполнении
etag string	Используется для согласованного выполнения операций чтения, изменения и записи. Возвращается: при успешном выполнении
indexStats dictionary	Статистика ресурса индекса. Возвращается: при успешном выполнении
shardsCount integer	Количество шардов в индексе. Возвращается: при успешном выполнении
vectorsCount string	Количество векторов в индексе. Возвращается: при успешном выполнении
metadataSchemaUri string	Указывает на YAML-файл в Google Cloud Storage с дополнительными сведениями, относящимися к этому индексу. Не задано, если у индекса нет дополнительных сведений. Возвращается: при успешном выполнении
name string	Имя ресурса индекса. Возвращается: при успешном выполнении
state string	Текущее состояние ресурса. Возвращается: всегда
updateTime string	Время последнего обновления индекса в формате RFC3339 UTC «Zulu», с точностью до наносекунд и максимум девятью знаками после запятой. Возвращается: при успешном выполнении

Авторы

Google Inc. (@googlecloudplatform)

Ссылки на коллекцию

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/google/cloud/gcp_vertexai_index_module.html