Обзор функций встраиванияCompatible with Milvus 2.6.x

Модуль Function в Milvus позволяет преобразовывать необработанные текстовые данные в векторные вкрапления путем автоматического вызова внешних провайдеров вкраплений (таких как OpenAI, AWS Bedrock, Google Vertex AI и т. д.). С модулем Function вам больше не нужно вручную взаимодействовать с API для встраивания - Milvus сам управляет всем процессом отправки запросов провайдерам, получения встраиваний и их хранения в ваших коллекциях. Для семантического поиска вам нужно предоставить только исходные данные запроса, но не вектор запроса. Milvus генерирует вектор запроса по той же модели, которую вы использовали для встраивания, сравнивает его с сохраненными векторами и возвращает наиболее релевантные результаты.

Ограничения

• Любое поле ввода, в которое встраивается модуль Function, всегда должно содержать значение; если будет предоставлен null, модуль выдаст ошибку.

• Модуль Function обрабатывает только те поля, которые явно определены в схеме коллекции; он не генерирует вставки для динамических полей.

• Встраиваемые поля ввода должны иметь тип VARCHAR.

• Модуль Function может внедрить поле ввода в:

  • FLOAT_VECTOR

  • INT8_VECTOR

  Преобразования в BINARY_VECTOR, FLOAT16_VECTOR или BFLOAT16_VECTOR не поддерживаются.

Поддерживаемые поставщики услуг встраивания

Провайдер	Типичные модели	Тип встраивания	Метод аутентификации
OpenAI	text-embedding-3-*	FLOAT_VECTOR	API-ключ
Azure OpenAI	На основе развертывания	FLOAT_VECTOR	Ключ API
DashScope	text-embedding-v3	FLOAT_VECTOR	Ключ API
Bedrock	amazon.titan-embed-text-v2	FLOAT_VECTOR	Пара AK/SK
ИИ Vertex	text-embedding-005	FLOAT_VECTOR	Учетная запись службы GCP в формате JSON
Voyage AI	voyage-3, voyage-lite-02	FLOAT_VECTOR / INT8_VECTOR	API-ключ
Cohere	embed-english-v3.0	FLOAT_VECTOR / INT8_VECTOR	Ключ API
SiliconFlow	BAAI/bge-large-zh-v1.5	FLOAT_VECTOR	ключ API
Обнимающееся лицо	Любая модель, обслуживаемая TEI	FLOAT_VECTOR	Дополнительный ключ API

Как это работает

На следующей схеме показано, как функция работает в Milvus.

1. Входной текст: Пользователи вводят в Milvus исходные данные (например, документы).

2. Генерация вкраплений: Модуль Function в Milvus автоматически вызывает сконфигурированный поставщик моделей для преобразования исходных данных в векторные вкрапления.

3. Хранить эмбеддинги: Полученные эмбеддинги хранятся в явно определенных векторных полях в коллекциях Milvus.

4. Запрашивать текст: Пользователи отправляют текстовые запросы в Milvus.

5. Семантический поиск: Milvus преобразует запросы в векторные вкрапления, проводит поиск по сходству с хранящимися вкраплениями и извлекает релевантные результаты.

6. Возврат результатов: Milvus возвращает приложению наиболее подходящие результаты.

Обзор функций встраивания

Настройка учетных данных

Прежде чем использовать функцию встраивания с Milvus, настройте учетные данные службы встраивания для доступа к Milvus.

Milvus позволяет предоставлять учетные данные службы встраивания двумя способами:

• Файл конфигурации (milvus.yaml):

  Пример в этой теме демонстрирует рекомендуемую настройку с помощью milvus.yaml.

• Переменные среды:

  Подробные сведения о настройке учетных данных с помощью переменных окружения см. в документации поставщика службы встраивания (например, OpenAI или Azure OpenAI).

На следующей схеме показан процесс настройки учетных данных через файл конфигурации Milvus (milvus.yaml) и последующего вызова функции в Milvus.

Переполнение конфигурации учетных данных

Шаг 1: Добавьте учетные данные в файл конфигурации Milvus

В файле milvus.yaml отредактируйте блок credential с записями для каждого провайдера, к которому вам нужен доступ:

# milvus.yaml credential store section
# This section defines all your authentication credentials for external embedding providers
# Each credential gets a unique name (e.g., aksk1, apikey1) that you'll reference elsewhere
credential:
  # For AWS Bedrock or services using access/secret key pairs
  # 'aksk1' is just an example name - you can choose any meaningful identifier
  aksk1:                       
    access_key_id: <YOUR_AK>      
    secret_access_key: <YOUR_SK>  
  
  # For OpenAI, Voyage AI, or other API key-based services
  # 'apikey1' is a custom name you choose to identify this credential  
  apikey1:                     
    apikey: <YOUR_API_KEY>        
  
  # For Google Vertex AI using service account credentials
  # 'gcp1' is an example name for your Google Cloud credentials
  gcp1:                        
    credential_json: <BASE64_OF_JSON>

Шаг 2: Настройте параметры провайдера

В том же файле конфигурации (milvus.yaml) отредактируйте блок function, чтобы указать Milvus, какой ключ использовать для встраивания вызовов служб:

function:
  textEmbedding:
    providers:
      openai:                         # calls OpenAI
        credential: apikey1           # Reference to the credential label
        # url:                        # (optional) custom url

      bedrock:                        # calls AWS Bedrock
        credential: aksk1             # Reference to the credential label
        region: us-east-2

      vertexai:                       # calls Google Vertex AI
        credential: gcp1              # Reference to the credential label
        # url:                        # (optional) custom url

      tei:                            # Built-in Tiny Embedding model
        enable: true                  # Whether to enable TEI model service

Дополнительные сведения о том, как применять конфигурацию Milvus, см. в разделе Настройка Milvus на лету.

Использование функции встраивания

После того как учетные данные настроены в файле конфигурации Milvus, выполните следующие шаги, чтобы определить и использовать функции встраивания.

Шаг 1: Определите поля схемы

Чтобы использовать функцию встраивания, создайте коллекцию с определенной схемой. Эта схема должна включать как минимум три необходимых поля:

• Первичное поле, которое уникально идентифицирует каждую сущность в коллекции.

• Скалярное поле, в котором хранятся исходные данные для встраивания.

• Векторное поле, зарезервированное для хранения векторных вкраплений, которые функция будет генерировать для скалярного поля.

Следующий пример определяет схему с одним скалярным полем "document" для хранения текстовых данных и одним векторным полем "dense" для хранения вкраплений, которые будут сгенерированы модулем Function. Не забудьте установить размерность вектора (dim) в соответствии с результатами выбранной вами модели встраивания.

from pymilvus import MilvusClient, DataType, Function, FunctionType

# Initialize Milvus client
client = MilvusClient(
    uri="http://localhost:19530",
)

# Create a new schema for the collection
schema = client.create_schema()

# Add primary field "id"
schema.add_field("id", DataType.INT64, is_primary=True, auto_id=False)

# Add scalar field "document" for storing textual data
schema.add_field("document", DataType.VARCHAR, max_length=9000)

# Add vector field "dense" for storing embeddings.
# IMPORTANT: Set dim to match the exact output dimension of the embedding model.
# For instance, OpenAI's text-embedding-3-small model outputs 1536-dimensional vectors.
# For dense vector, data type can be FLOAT_VECTOR or INT8_VECTOR
schema.add_field("dense", DataType.FLOAT_VECTOR, dim=1536)

// java

// nodejs

// go

# restful

Шаг 2: Добавьте функцию встраивания в схему

Модуль Function в Milvus автоматически преобразует исходные данные, хранящиеся в скалярном поле, во вкрапления и сохраняет их в явно определенном векторном поле.

Пример ниже добавляет модуль Function (openai_embedding), который преобразует скалярное поле "document" в эмбеддинги, сохраняя полученные векторы в векторном поле "dense", определенном ранее.

# Define embedding function (example: OpenAI provider)
text_embedding_function = Function(
    name="openai_embedding",                  # Unique identifier for this embedding function
    function_type=FunctionType.TEXTEMBEDDING, # Type of embedding function
    input_field_names=["document"],           # Scalar field to embed
    output_field_names=["dense"],             # Vector field to store embeddings
    params={                                  # Provider-specific configuration (highest priority)
        "provider": "openai",                 # Embedding model provider
        "model_name": "text-embedding-3-small",     # Embedding model
        # "credential": "apikey1",            # Optional: Credential label
        # Optional parameters:
        # "dim": "1536",       # Optionally shorten the vector dimension
        # "user": "user123"    # Optional: identifier for API tracking
    }
)

# Add the embedding function to your schema
schema.add_function(text_embedding_function)

// java

// nodejs

// go

# restful

Параметр	Описание	Пример Значение
name	Уникальный идентификатор для функции встраивания в Milvus.	"openai_embedding"
function_type	Тип используемой функции. Для встраивания текста установите значение FunctionType.TEXTEMBEDDING. Примечание: Milvus принимает для этого параметра значения FunctionType.BM25 (для преобразования с разреженной вставкой) и FunctionType.RERANK (для ранжирования). Подробности см. в разделе Обзор полнотекстового поиска и ранжирования по распаду.	FunctionType.TEXTEMBEDDING
input_field_names	Скалярное поле, содержащее исходные данные для встраивания. В настоящее время этот параметр принимает только одно имя поля.	["document"]
output_field_names	Векторное поле для хранения сгенерированных вкраплений. В настоящее время этот параметр принимает только одно имя поля.	["dense"]
params	Словарь, содержащий конфигурации встраивания. Примечание: Параметры внутри params зависят от поставщиков моделей встраивания.	{...}
provider	Поставщик модели встраивания.	"openai"
model_name	Указывает, какую модель встраивания использовать.	"text-embedding-3-small"
credential	Метка учетной записи, определенная в разделе верхнего уровня credential: на сайте milvus.yaml. При указании этого параметра Milvus извлекает соответствующую пару ключей или API-токен и подписывает запрос на стороне сервера. Если метка не указана (None), Milvus возвращается к учетной записи, явно настроенной для провайдера целевой модели в milvus.yaml. Если метка неизвестна или отсутствует ключ, вызов завершается неудачей.	"apikey1"
dim	Количество измерений для выходных вкраплений. Для моделей OpenAI третьего поколения вы можете сократить полный вектор, чтобы снизить стоимость и время ожидания без существенной потери семантической информации. Более подробную информацию можно найти в блоге анонса OpenAI. Примечание: Если вы сокращаете размерность вектора, убедитесь, что значение dim, указанное в методе add_field схемы для векторного поля, совпадает с конечной выходной размерностью вашей функции встраивания.	"1536"
user	Идентификатор уровня пользователя для отслеживания использования API.	"user123"

Шаг 3: Настройте индекс

Определив схему с необходимыми полями и встроенной функцией, настройте индекс для коллекции. Чтобы упростить этот процесс, используйте AUTOINDEX в качестве index_type, опция, которая позволяет Milvus выбрать и настроить наиболее подходящий тип индекса, основываясь на структуре ваших данных.

# Prepare index parameters
index_params = client.prepare_index_params()

# Add AUTOINDEX to automatically select optimal indexing method
index_params.add_index(
    field_name="dense",
    index_type="AUTOINDEX",
    metric_type="COSINE" 
)

// java

// nodejs

// go

# restful

Шаг 4: Создание коллекции

Теперь создайте коллекцию, используя заданную схему и параметры индекса.

# Create collection named "demo"
client.create_collection(
    collection_name='demo', 
    schema=schema, 
    index_params=index_params
)

// java

// nodejs

// go

# restful

Шаг 5: Вставка данных

После настройки коллекции и индекса вы готовы к вставке исходных данных. В этом процессе вам нужно только предоставить исходный текст. Модуль Function, который мы определили ранее, автоматически генерирует соответствующий разреженный вектор для каждой текстовой записи.

# Insert sample documents
client.insert('demo', [
    {'id': 1, 'document': 'Milvus simplifies semantic search through embeddings.'},
    {'id': 2, 'document': 'Vector embeddings convert text into searchable numeric data.'},
    {'id': 3, 'document': 'Semantic search helps users find relevant information quickly.'},
])

// java

// nodejs

// go

# restful

Шаг 6: Выполните поиск вектора

После вставки данных выполните семантический поиск по необработанному тексту запроса. Milvus автоматически преобразует ваш запрос в вектор вложения, извлекает релевантные документы на основе сходства и возвращает результаты с наибольшим количеством совпадений.

# Perform semantic search
results = client.search(
    collection_name='demo', 
    data=['How does Milvus handle semantic search?'], # Use text query rather than query vector
    anns_field='dense',   # Use the vector field that stores embeddings
    limit=1,
    output_fields=['document'],
)

print(results)

# Example output:
# data: ["[{'id': 1, 'distance': 0.8821347951889038, 'entity': {'document': 'Milvus simplifies semantic search through embeddings.'}}]"]

// java

// nodejs

// go

# restful

Для получения дополнительной информации об операциях поиска и запроса обратитесь к разделу Базовый векторный поиск и запрос.

ЧАСТО ЗАДАВАЕМЫЕ ВОПРОСЫ

В чем разница между настройкой учетных данных в milvus.yaml и переменных окружения?

Оба метода работают, но использование milvus.yaml является рекомендуемым подходом, поскольку обеспечивает централизованное управление учетными данными и согласованное именование учетных данных для всех провайдеров. При использовании переменных окружения имена переменных зависят от поставщика услуг встраивания, поэтому обратитесь к специальной странице каждого поставщика, чтобы понять, какие именно имена переменных окружения требуются (например, OpenAI или Azure OpenAI).

Что произойдет, если я не укажу параметр учетных данных в определении функции?

Milvus придерживается следующего порядка разрешения учетных данных:

1. Сначала он ищет учетные данные по умолчанию, настроенные для данного провайдера в файле milvus.yaml.
2. Если в milvus.yaml нет мандата по умолчанию, он возвращается к переменным окружения (если они настроены).
3. Если ни учетные данные milvus.yaml, ни переменные окружения не настроены, Milvus выдаст ошибку.

Как проверить, что вставки генерируются правильно?

Проверить можно следующим образом:

1. Запросить коллекцию после вставки, чтобы проверить, содержит ли векторное поле данные.
2. Убедиться, что длина векторного поля соответствует ожидаемым размерам
3. Выполнить простой поиск по сходству, чтобы убедиться, что вкрапления дают значимые результаты.

Могу ли я при поиске сходства использовать вектор запроса, а не необработанный текст?

Да, вы можете использовать предварительно вычисленные векторы запросов вместо необработанного текста для поиска сходства. Хотя модуль Function автоматически преобразует необработанные текстовые запросы во вкрапления, вы также можете напрямую указать векторные данные в параметре data в операции поиска. Примечание: размерность предоставленного вами вектора запроса должна соответствовать размерности векторных вкраплений, сгенерированных вашим функциональным модулем.

Пример:

# Using raw text (Function module converts automatically)
results = client.search(
    collection_name='demo', 
    data=['How does Milvus handle semantic search?'],
    anns_field='dense',
    limit=1
)

# Using pre-computed query vector (must match stored vector dimensions)
query_vector = [0.1, 0.2, 0.3, ...]  # Must be same dimension as stored embeddings
results = client.search(
    collection_name='demo', 
    data=[query_vector],
    anns_field='dense',
    limit=1
)

// java

// nodejs

// go

# restful