vectorflow
1.0.0
벡터 플로우는 오픈 소스, 높은 처리량, 결함 허용 벡터 임베딩 파이프 라인입니다. 간단한 API 요청을 사용하면 벡터 데이터베이스에 청크, 임베디드 및 저장 될 원시 데이터를 보낼 수 있습니다.
이 현재 버전은 MVP입니다. 프로덕션에서 Kubernetes와 함께 사용하는 것이 좋습니다 (자세한 내용은 아래 참조). 텍스트 기반 파일의 경우 TXT, PDF, HTML 및 DOCX를 지원합니다.
세 가지 명령으로 로컬에서 벡터 플로우를 실행할 수 있습니다.
git clone https://github.com/dgarnitz/vectorflow.git
cd vectorflow
./setup.sh
문서를 로컬로 포함시키기 위해 Python Application의 가상 환경에 Vectorflow Client 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)
PIP를 통해 클라이언트 기능을 활용하기 위해 벡터 플로 리 레포를 복제 할 필요는 없습니다 . 자세한 내용은 client 디렉토리의 README.md 를 참조하십시오.
testing_clients 스크립트 사용 방법에 대한 자세한 내용은 부록을 참조하십시오.
벡터 플로우를 실행하는 가장 좋은 방법은 docker compose 통한 것입니다. Mac 에서이 작업을 실행하는 경우 여기에서 지시 한대로 Docker 권한을 문서 폴더에서 읽을 수 있도록 권한을 부여하십시오. 이것이 실패하면 docker-compose.yml 에서 volume 섹션을 제거하십시오.
먼저 모든 환경 변수에 대한 루트에서 폴더, env_scripts 작성한 다음 env_scripts 폴더에서 env_vars.env 작성하여 아래에 언급 된 모든 환경 변수를 추가하십시오. qdrant, milvus 또는 로컬로 Weaviate를 실행중인 경우 LOCAL_VECTOR_DB 변수 만 설정하면됩니다.
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, Postgres, Min.io를 현지 Docker Repo로 끌어 당기십시오. 또한 로컬에서 벡터 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 객체 저장소를 설정하는 스크립트를 실행하고 있습니다. 이 컨테이너는 스크립트가 완료된 후에 멈 춥니 다. Qdrant의 경우 Qdrant 클라이언트 Python 패키지가 작업 해야하는 버전이므로 버전 1.9.1을 가져와야합니다.
Vectorflow를 사용하는 가장 좋은 방법은 Python 클라이언트와 함께하는 것입니다.
개발에 벡터 플로우를 사용하려면 API의 URL에 HTTP 요청을하십시오 (예 : localhost:8000 개발 시스템에서 8000 또는 다른 Docker 컨테이너 내에서 vectorflow_api:8000 .
모든 요청에는 이전에 정의한 INTERNAL_API_KEY Env var와 동일한 Authorization 키가있는 HTTP 헤더가 필요합니다 (위 참조). 벡터 DB의 클라우드 기반 인스턴스에 연결하는 경우 HTTP 헤더 X-VectorDB-Key X-EmbeddingAPI-Key 함께 벡터 데이터베이스 API 키를 전달해야합니다. . Huggingface 문장 변압기 임베딩에는 API 키가 필요하지 않지만 필요한 모델로 컨테이너를 실행하려면 위의 단계를 따라야합니다.
VectorFlow는 현재 PENECONE, QDRANT 및 WEAVIET VECTOR 데이터베이스를 지원합니다.
임베딩을위한 단일 파일을 제출하려면 'Content-Type: multipart/form-data' 헤더 및 다음 페이로드를 첨부 한 파일을 사용하여 /embed Endpoint에 POST 요청을 작성하십시오.
{
'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
}
현재이 엔드 포인트는 시간 초과 문제로 인해 최대 25MB의 단일 파일 업로드 만 지원합니다. 더 이상 사용되지 않을 수 있습니다.
임베딩을 위해 여러 파일을 제출하려면 /jobs 엔드 포인트에 대한 POST 요청을 작성하십시오. 페이로드는 여러 파일을 첨부하는 방식을 제외하고는 단일 파일 임베딩과 동일합니다.
{
'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 해야합니다. 기존의 사후 요청으로 보내지 않으면 실패합니다.
이 엔드 포인트는 업로드 된 파일 당 하나의 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 의 상태를 확인하려면이 엔드 포인트 : /jobs/status 에 대한 POST 요청을하십시오. 요청 본문은 양식입니다.
{
'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
ID는 중복 제거 및 Idempotency에 사용될 수 있습니다. weaviate의 경우 ID를 vectorflow_id 라고합니다.
우리는 근처 Futuer에서이를 감가 상각하여 동적으로 감지 및/또는 구성 가능한 스키마를 도로로 지원합니다.
Vectorflow의 내장 된 덩어리는 문자가 아닌 토큰으로 카운트합니다. 벡터 플로우의 chunk 다음 키를 가진 사전입니다.
text: str
vector: list[float]
작업자의 Docker Image를 빌드하기 전에 Methods, chunker(source_data: list[str]) 와 함께 파일, custom_chunker.py 추가하여 src/worker 정의 chunker를 실행할 수 있습니다. 이 chunker는 위의 표준을 준수하는 chunk 사전 목록을 반환해야합니다.
JSON 직렬화 가능한 chunk 사전에 원하는 키를 추가 할 수 있습니다. 즉, 사용자 정의 클래스 나 기능, DateTimes 유형 또는 원형 코드 참조가 없음을 의미합니다. 이 사용자 정의 청크를 사용하여 원하는 스키마를 사용하여 메타 데이터를 벡터 DB에 업로드 할 수 있습니다.
청킹 및 임베딩을 생성하는 데만 벡터 플로우를 사용하려면 /embed 요청 본문에 WebhookURL 매개 변수를 전달하고 X-Webhook-Key 헤더로 전달하십시오. Vectorflow는 모든 엔드 포인트에 다시 쓰기 위해 Webhook 키가 필요하다고 가정합니다. 임베딩은 위에서 설명한 chunk 사전의 소스 청크와 함께 다시 전송됩니다. 이것은 다음 형식으로 JSON으로 전송됩니다.
{
'Embeddings': list[dict],
'DocumentID': str,
'JobID': int
}
포함하려는 어떤 청크를 검증하려면, /embed 요청 본문에 ChunkValidationURL 매개 변수를 전달하십시오. 다음 JSON 페이로드 {"chunks": chunked_data} 로 요청을 보냅니다. 여기서 chunked_data chunk 사전 목록입니다. 임베딩을위한 유효한 청크 목록이 포함 된 주요 valid_chunks 포함하는 JSON이 다시 예상됩니다. 이 엔드 포인트는 기본적으로 30 초 후에 타임 아웃하지만 응용 프로그램 코드에서 구성 할 수 있습니다.
벡터 플로는 AWS S3와 통합됩니다. 파일 대신 HTTP 본문에서 사전 서명 된 S3 URL을 전달할 수 있습니다. Form Field PreSignedURL 사용하고 종말점 /s3 에 부딪칩니다. 이 엔드 포인트는 /embed 엔드 포인트와 동일한 구성 및 제한을 갖습니다.
Vectorflow는 Posthog를 사용하여 익명 사용에 대한 데이터를 익명으로 수집합니다. 이것은 개인적으로 식별 가능한 정보를 수집하지 않습니다. 그래도 비활성화하려면 env_vars.env 에 다음 Enviroment 변수를 추가하십시오.
TELEMETRY_DISABLED=True
./kube/scripts/deploy-local-k8s.sh 사용하여 Minikube와 함께 Kubernetes에서 벡터 플로우를 로컬로 실행할 수 있으며 kube/ 에있는 모든 YAML 파일을 적용합니다. Docker, Minikube 및 Kubectl을 설치하지 않은 경우이 스크립트는 작동하지 않습니다.
이 스크립트는 먼저 이미지를 로컬로 빌드 한 다음 Minikube로 전송합니다. Minikube에서 사용할 수있는 이미지를 확인하려면 다음을 실행하십시오.
eval $(minikube docker-env)
docker images
개발 시스템의 클러스터에있는 리소스에 액세스하려면 minikube tunnel 실행해야합니다. 설정 스크립트는 로컬 Docker 컨텍스트의 이미지를 Minikube의 이미지로로드합니다.
kube/ 의 Yaml 파일을 생산 배포의 기초로 사용할 수 있지만 특정 클러스터의 요구에 대해 약간 사용자 정의해야합니다. 도움이 필요한 경우 저희에게 연락하십시오.
우리는 지역 사회의 피드백을 좋아합니다. 이 프로젝트를 개선하는 방법에 대한 아이디어가 있다면 문제를 열거 나 불화에 참여하는 것이 좋습니다. dgarnitz 와 danmeier2 태그하십시오.
우리의 로드맵은 아래 섹션에 요약되어 있으며 우리는 그것을 구축하는 데 도움이됩니다. 우리의 열린 문제는 시작하기에 좋은 장소이며 여기서 볼 수 있습니다. 거기에 나열되지 않은 작업을 수행하려면 PR을 제출하기 전에 제안 된 접근 방식을 염두에두고 문제를 여는 것이 좋습니다.
모든 PR에 dgarnitz 태그하고 변경 사항을 반영하도록 ReadMe를 업데이트하십시오 .
PR을 제출할 때 추가 한 기능을 다루기 위해 단위 테스트를 추가하십시오. 회귀 버그가 없는지 확인하려면 기존 테스트를 다시 실행하십시오. src 디렉토리에서 실행하십시오. 개별 테스트 사용을 실행하려면 :
python -m unittest module.tests.test_file.TestClass.test_method
파일 사용에서 모든 테스트를 실행하려면 다음과 같습니다.
python -m unittest module.tests.test_file
엔드 투 엔드 테스트를 위해서는 Docker-Compose를 사용하여 빌드 및 실행하는 것이 좋습니다. 그러나 변경중인 컨테이너를 내리고 개발 시스템에서 로컬로 실행하십시오. 이렇게하면 이미지를 지속적으로 재건하고 컨테이너를 다시 실행할 필요가 없습니다. Docker 컨테이너가 개발 기계와 통신 할 수 있도록 개발 기계 터미널의 환경 변수를 올바른 값 (즉, rabbitmq 또는 postgres 대신 localhost )으로 변경하십시오. 로컬로 작동하면 Docker-Compose의 모든 것을 사용하여 최종 테스트를 수행 할 수 있습니다.
PR을 열기 전에 모든 변경 사항이 Docker-Compose와 작동하는지 확인하십시오.
또한 코드가 끝까지 끝까지 작동한다는 스크린 샷과 같은 검증 증거를 추가하는 것이 좋습니다.
VectorFlow를 사용하는 쉬운 방법 중 하나는 testing_clients/ Directory에 위치한 테스트 클라이언트와 관련이 있습니다. qickly 업로드 데이터에 대한 구성이 다른 여러 스크립트가 있습니다. testing_clients/standard_upload_client.py 부터 시작하는 것이 좋습니다.이 스크립트를 실행하면 Open AI ADA와 함께 포함 된 단일 문서를 VectorFlow에 제출하고 로컬 QDRANT 인스턴스에 업로드합니다. 구성과 일치하도록 값을 변경할 수 있습니다. 여러 파일을 한 번에 업로드하려면 testing_clients/streaming_upload_client.py 사용하십시오
TESTING_ENV 변수는 VectorDBMetadata 의 environment 필드와 동일하며, 이는 Pincone의 환경, weaviate의 클래스, Qdrant의 컬렉션 등에 해당합니다. testing_clients 디렉토리에는 vectorflow를 실행하기 위해 따라갈 수있는 샘플 스크립트가 있습니다. 생성 된 env_scrips/env_vars.sh 스크립트에 임베딩 및 데이터베이스 키를 추가하고 testing_clients/standard_upload_client.py 에서 filepath 변수를 설정하여 포함 할 파일을 가리 키십시오. 그런 다음 실행 :
source env_scrips/env_vars.sh
python testing-clients/standard_upload_client.py
여러 파일을 한 번에 업로드하려면 testing_clients/streaming_upload_client.py 사용하십시오
시스템을 수동으로 설정하고 구성하는 방법에 대한 자세한 설명은 위를 참조하십시오. setup 스크립트는 컴퓨터에서 개발 환경을 생성하지 않으며 Docker-Compose를 설정하고 실행합니다. Windows에서 Vectorflow를 사용하는 것은 조언하지 않습니다.
검색 'Content-Type: multipart/form-data' 수행하려면 이미지 파일을 첨부 한 후 /images/search 엔드 포인트에 POST 요청을 보내십시오.
{
'ReturnVectors': boolean,
'TopK': integer, less than 1000,
'VectorDBMetadata={
"vector_db_type": "PINECONE | QDRANT | WEAVIATE",
"index_name": "index_name",
"environment": "env_name"
}'
}
모든 요청에는 이전에 정의한 INTERNAL_API_KEY Env var와 동일한 Authorization 키가있는 HTTP 헤더가 필요합니다 (위 참조). 벡터 DB의 클라우드 기반 인스턴스에 연결하는 경우 HTTP 헤더 X-VectorDB-Key 사용하여 벡터 데이터베이스 API 키를 전달해야합니다.
이미지 유사성 검색은 상단 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를 실행합니다. 작업자를 실행하기 위해 포트 인수가 필요하지 않습니다.
