vectorflow
1.0.0
VectorFlow - это с открытым исходным кодом, высокая пропускная способность, устойчивый к разлому трубопровод встроенного вектора. С помощью простого запроса API вы можете отправлять необработанные данные, которые будут сохранены, встроены и хранятся в любой векторной базе данных или возвращены вам обратно.
Эта текущая версия - MVP. Мы рекомендуем использовать его с Kubernetes в производстве (для получения подробной информации см. Ниже). Для текстовых файлов он поддерживает TXT, PDF, HTML и DOCX.
С тремя командами вы можете запустить VectorFlow локально:
git clone https://github.com/dgarnitz/vectorflow.git
cd vectorflow
./setup.sh
Чтобы начать встроение документов локально, установите библиотеку Python Client VectorFlow в виртуальную среду вашего приложения Python.
pip install vectorflow-client
Затем запустите следующее
from vectorflow-client.client.vectorflow import Vectorflow
vectorflow = Vectorflow()
vectorflow.embeddings_api_key = os.getenv("OPEN_AI_KEY")
paths = ['path_to_your_file1', 'path_to_your_file2', ...]
response = vectorflow.upload(paths)
Вам не нужно клонировать репо VectorFlow, чтобы использовать функциональность клиента через PIP. Для получения дополнительных инструкций см. README.md в client каталоге.
См. Приложение для получения подробной информации о том, как использовать сценарии testing_clients .
Лучший способ запуска VectorFlow - через docker compose . Если вы запускаете это на Mac, пожалуйста, предоставьте докеру разрешения для чтения из папки документов, как указано здесь. Если это не удалось, удалите раздел volume с docker-compose.yml .
Сначала создайте папку env_scripts , в корне для всех переменных среды, а затем создайте env_vars.env в папке env_scripts , чтобы добавить все переменные среды, упомянутые ниже. Вам нужно установить переменную LOCAL_VECTOR_DB только если вы используете Qdrant, Milvus или Weaviate локально.
INTERNAL_API_KEY=your-choice
POSTGRES_USERNAME=postgres
POSTGRES_PASSWORD=your-choice
POSTGRES_DB=vectorflow
POSTGRES_HOST=postgres
RABBITMQ_USERNAME=guest
RABBITMQ_PASSWORD=guest
RABBITMQ_HOST=rabbitmq
LOCAL_VECTOR_DB=qdrant | weaviate
API_STORAGE_DIRECTORY=/tmp
MINIO_ACCESS_KEY=minio99
MINIO_SECRET_KEY=minio123
MINIO_ENDPOINT=minio:9000
MINIO_BUCKET=vectorflow
Вы можете выбрать переменную для INTERNAL_API_KEY , POSTGRES_PASSWORD и POSTGRES_DB , но они должны быть установлены.
Убедитесь, что вы втягиваете MQ Rabbit MQ, Postgres, Min.io в местный репо. Мы также рекомендуем запустить векторный DB в локальном масштабе, поэтому обязательно вытащите изображение того, что вы используете. Наш файл docker-compose по умолчанию будет развернуть Qdrant и создаст два индекса/коллекции. Если вы планируете запустить Milvus или Weaviate, вам придется настроить их самостоятельно.
docker pull rabbitmq
docker pull postgres
docker pull qdrant/qdrant | docker pull semitechnologies/weaviate
docker pull minio/minio
Затем беги:
docker-compose build --no-cache
docker-compose up -d
Обратите внимание, что в контейнерах init запускается сценарий, который устанавливает схему базы данных, вектор DB и Min.io Store. Эти контейнеры останавливаются после завершения сценария. Для Qdrant обязательно вытяните версию 1.9.1, так как это версия, с которой должен работать пакет Qdrant Client Python.
Лучший способ использовать VectorFlow - это клиент Python.
Чтобы использовать VectorFlow для разработки, сделайте HTTP -запрос на URL вашего API - например, localhost:8000 из вашей машины разработки или vectorflow_api:8000 из другого контейнера Docker.
Все запросы требуют заголовка HTTP с ключом Authorization , который такой же, как ваш INTERNAL_API_KEY env var, который вы определили ранее (см. Выше). Вы должны передать ключ API векторной базы данных с помощью HTTP Header X-VectorDB-Key если вы используете соединение с облачным экземпляром вектора DB, и клавиша API встраивания с X-EmbeddingAPI-Key если вы используете OpenAI Полем Внедрения трансформатора предложений HuggingFace не требуют ключа API, но вы должны выполнить вышеуказанные шаги, чтобы запустить контейнер с необходимой моделью.
VectorFlow в настоящее время поддерживает базы данных Pinecone, Qdrant и Weaviate Vector.
Чтобы отправить один файл для внедрения, сделайте запрос POST в конечную точку /embed с прикрепленным файлом, заголовок 'Content-Type: multipart/form-data' и следующая полезная нагрузка:
{
'SourceData=path_to_txt_file'
'LinesPerBatch=4096'
'EmbeddingsMetadata={
"embeddings_type": "OPEN_AI",
"chunk_size": 512,
"chunk_overlap": 128,
"chunk_strategy": "EXACT | PARAGRAPH | SENTENCE | CUSTOM",
"model": "text-embedding-3-small | text-embedding-3-large | text-embedding-ada-002"
}'
'VectorDBMetadata={
"vector_db_type": "PINECONE | QDRANT | WEAVIATE",
"index_name": "index_name",
"environment": "env_name"
}'
'DocumentID=your-optional-internal-tracking-id'
}
Это создаст job , и вы получите следующую полезную нагрузку:
{
'message': f"Successfully added {batch_count} batches to the queue",
'JobID': job_id
}
Прямо сейчас эта конечная точка поддерживает загрузку отдельных файлов за раз, до 25 МБ из -за проблем с тайм -аутом. Обратите внимание, что это может быть устарело.
Чтобы отправить несколько файлов для внедрения, сделайте запрос POST в конечную точку /jobs . Полезная нагрузка такая же, как и для встраивания в одном файле, за исключением того, что прикрепление нескольких файлов отличается:
{
'files=[
('file', ('test_pdf.pdf', open(file1_path, 'rb'), 'application/octet-stream')),
('file', ('test_medium_text.txt', open(file2_path, 'rb'), 'application/octet-stream'))
]'
}
Примечание. Вы должны stream файлы в конечную точку, а не отправлять его в качестве обычного запроса POST, иначе он потерпит неудачу.
Эта конечная точка создаст одну job на загрузку файла. Вы получите следующую полезную нагрузку JSON:
{
'successful_uploads': successfully_uploaded_files,
'failed_uploads': failed_uploads,
'empty_files_count': empty_files_count,
'duplicate_files_count': duplicate_files_count
}
Где successfully_uploaded_files - это список кортежей, содержащих (file name, job id) и failed_uploads , - это список имен файлов, которые не загрузили, чтобы вы могли повторно их.
Чтобы проверить статус job , сделайте запрос GET в эту конечную точку: /jobs/<int:job_id>/status . Ответ будет в форме:
{
'JobStatus': job_status
}
Чтобы проверить статус многократного job , сделайте запрос POST в этой конечной точке: /jobs/status . Тело запроса будет в форме:
{
'JobIDs': job_ids
}
и ответ будет в форме
{
'Jobs': [{'JobID': job_id, 'JobStatus': job_status}, ...]}
Есть пример в testing_clients/get_jobs_by_ids.py .
VectorFlow обеспечивает стандартизированную схему для загрузки данных в векторный хранилище:
id: string
source_data: string
source_document: string
embeddings: float array
Идентификатор может быть использован для дедупликации и идентификации. Обратите внимание на Weaviate, идентификатор называется vectorflow_id .
Мы планируем снизить это в ближайшем будущем для поддержки динамически обнаруженных и/или настраиваемых схем в будущем.
Vectorflow встроен в Chunkers, что считается токеном, а не по характеру. chunk в VectorFlow - это словарь, который имеет следующие ключи:
text: str
vector: list[float]
Вы можете запустить пользовательский кусок, добавив файл, custom_chunker.py , методом, chunker(source_data: list[str]) в каталог src/worker до создания изображения Docker для работника. Этот кусочек должен вернуть список chunk -словарей, которые соответствуют вышеуказанному стандарту.
Вы можете добавить любые ключи, которые вы хотите, в chunk -словарь, если он сериализует его JSON , что означает отсутствие пользовательских классов или функций, типов дат -времени или ссылок на круговой код. Вы можете использовать этот пользовательский кусок, чтобы затем загрузить метаданные в вектор DB с любой схемой, которую вы желаете.
Если вы хотите использовать VectorFlow только для подготовки и генерации внедрения, передайте параметр WebhookURL в теле запроса /embed и X-Webhook-Key в качестве заголовка. VectorFlow предполагает, что для записи требуется ключ Webhook. Встроения отправляются обратно вместе с кусками исходных работ в словаре chunk изложенным выше. Это отправлено как JSON со следующей формой:
{
'Embeddings': list[dict],
'DocumentID': str,
'JobID': int
}
Если вы хотите проверить, какие куски вы хотите встроить, передайте параметр ChunkValidationURL в теле запроса /embed . Это отправит запрос со следующей полезной нагрузкой JSON, {"chunks": chunked_data} , где chunked_data - это список словарей chunk . Он будет ожидать, что JSON, содержащий ключ valid_chunks со списком действительных кусков для внедрения. Эта конечная точка будет время ожидания через 30 секунд по умолчанию, но может быть настроена в коде приложения.
VectorFlow интегрирован с AWS S3. Вы можете передать предварительно подписанный URL S3 в теле HTTP вместо файла. Используйте поле формы PreSignedURL и нажмите на конечную точку /s3 . Эта конечная точка имеет такую же конфигурацию и ограничения, что и конечная точка /embed .
VectorFlow использует Posthog для анонимного сбора данных об использовании. Это не собирает какую -либо личную информацию. Если вы хотите отключить его, добавьте следующую переменную среды env_vars.env :
TELEMETRY_DISABLED=True
Вы можете запустить VectorFlow локально в Kubernetes с Minikube, используя ./kube/scripts/deploy-local-k8s.sh , что применяет все файлы YAML, расположенные в kube/ . Этот сценарий не будет работать, если вы не установили Docker, Minikube и Kubectl.
Этот сценарий сначала построит изображения локально, а затем перенесет их в Minikube. Если вы хотите проверить, какие изображения доступны в Minikube, запустите следующее:
eval $(minikube docker-env)
docker images
Вам нужно будет запустить minikube tunnel чтобы получить доступ к ресурсам, расположенным в кластере от вашей машины разработки. Сценарий настройки загрузит изображения из вашего локального контекста докера в Minikube's.
Вы можете использовать файлы YAML в kube/ в качестве основы для развертывания производства, но вам нужно будет немного настроить потребности вашего конкретного кластера. Свяжитесь с нами, если вам нужна помощь.
Мы любим обратную связь от сообщества. Если у вас есть представление о том, как сделать этот проект лучше, мы рекомендуем вам открыть проблему или присоединиться к нашему разногласию. Пожалуйста, отметьте dgarnitz и danmeier2 .
Наша дорожная карта указана в разделе ниже, и мы хотели бы помочь в ее создании. Наши открытые проблемы - отличное место для начала, и можно просмотреть здесь. Если вы хотите поработать над чем -то, что не указано там, мы рекомендуем вам открыть проблему с предложенным подходом, прежде чем отправить PR.
Пожалуйста, отметьте dgarnitz на всех PRS и обновите Readme , чтобы отразить ваши изменения.
При отправке PR, пожалуйста, добавьте тесты блоков, чтобы покрыть добавленную вами функциональность. Пожалуйста, перезапустите существующие тесты, чтобы убедиться, что нет регрессивных ошибок. Забежать от каталога src . Чтобы запустить отдельное использование теста:
python -m unittest module.tests.test_file.TestClass.test_method
Чтобы запустить все тесты в использовании файла:
python -m unittest module.tests.test_file
Для сквозного тестирования рекомендуется создавать и запустить, используя Docker-Compose, но снимайте контейнер, который вы изменяете, и запустите его локально на вашей машине разработки. Это будет избежать необходимости постоянно перестраивать изображения и перезапустить контейнеры. Обязательно измените переменные среды в вашем терминале машины разработки на правильные значения (то есть localhost вместо rabbitmq или postgres ), чтобы контейнеры Docker могли общаться с вашим машиной разработки. Как только он работает локально, вы можете выполнить окончательный тест со всем в докере.
Пожалуйста, убедитесь, что все изменения работают с докером, перед открытием PR.
Мы также рекомендуем добавить доказательства проверки, такие как скриншоты, которые показывают, что ваш код работает в конце конечного потока.
Один простой способ использования VectorFlow - это наши тестирующие клиенты, расположенные в testing_clients/ Directory. Есть несколько сценариев, с различными конфигурациями для загрузки Qickly. Мы рекомендуем начинать с testing_clients/standard_upload_client.py - Запуск этого скрипта отправит один документ в VectorFlow для внедрения с Open AI ADA и загрузки в локальный экземпляр Qdrant. Вы можете изменить значения в соответствии с вашей конфигурацией. Чтобы загрузить несколько файлов одновременно, используйте testing_clients/streaming_upload_client.py
Обратите внимание, что переменная TESTING_ENV является эквивалентом поля environment в VectorDBMetadata , которая соответствует среде в Пинконе, классе в Weaviate, коллекции в Qdrant и т. Д. В каталоге testing_clients есть образцы сценариев, которые вы можете следовать для запуска VectorFlow. Добавьте свои клавиши встраивания и базы данных в сценарий env_scrips/env_vars.sh , который был сгенерирован, и установите переменную filepath в testing_clients/standard_upload_client.py чтобы указать на файл, который вы хотите внедрить. Затем беги:
source env_scrips/env_vars.sh
python testing-clients/standard_upload_client.py
Чтобы загрузить несколько файлов одновременно, используйте testing_clients/streaming_upload_client.py
См. Выше более подробное описание того, как вручную настроить и настроить систему. Обратите внимание, что сценарий setup не будет создавать среду разработки на вашем компьютере, он только устанавливается и запускает Docker-Compose. Мы не советуем использовать VectorFlow в Windows.
Чтобы выполнить поиск, отправьте запрос POST по адресу /images/search 'Content-Type: multipart/form-data'
{
'ReturnVectors': boolean,
'TopK': integer, less than 1000,
'VectorDBMetadata={
"vector_db_type": "PINECONE | QDRANT | WEAVIATE",
"index_name": "index_name",
"environment": "env_name"
}'
}
Все запросы требуют заголовка HTTP с ключом Authorization , который такой же, как ваш INTERNAL_API_KEY env var, который вы определили ранее (см. Выше). Вы должны передать ключ API Vector Database API с помощью HTTP Header X-VectorDB-Key если вы используете подключение к облачному экземпляру вектора DB.
Поиск сходства изображений вернет объект ответа, содержащий верхние k совпадения, плюс необработанные векторы, если запрошены, со следующей формой:
{
"similar_images": list of match objects
"vectors": list of list of floats
}
где объекты `match`` определяются как:
{
"id": str,
"score": float,
"metadata": {"source_document" : str}
}
Если вы хотите использовать docker build и docker run для сборки и запуска отдельных изображений вместо docker-compose Следуйте этим шагам:
cd src/docker build --file api/Dockerfile -t vectorflow_api:latest . Чтобы построить - не забудьте период в концеdocker run --network=vectorflow --name=vectorflow_api -d --env-file=../env_scripts/env_vars.env -p 8000:8000 vectorflow_api:latest для запуска API. Вам не нужен аргумент порта, чтобы запустить работника
