vectorflow
1.0.0
VectorFlow adalah sumber embedding vektor toleran terhadap sumber yang tinggi, throughput tinggi. Dengan permintaan API sederhana, Anda dapat mengirim data mentah yang akan dipotong, tertanam dan disimpan dalam database vektor apa pun atau kembali kepada Anda.
Versi saat ini adalah MVP. Kami merekomendasikan menggunakannya dengan Kubernet dalam produksi (lihat di bawah untuk detailnya). Untuk file berbasis teks, ini mendukung TXT, PDF, HTML dan DOCX.
Dengan tiga perintah Anda dapat menjalankan vectorflow secara lokal:
git clone https://github.com/dgarnitz/vectorflow.git
cd vectorflow
./setup.sh
Untuk mulai menanamkan dokumen secara lokal, instal Perpustakaan Python Klien VectorFlow di lingkungan virtual aplikasi Python Anda.
pip install vectorflow-client
Kemudian jalankan berikut ini
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)
Anda tidak perlu mengkloning repo vectorflow untuk memanfaatkan fungsionalitas klien melalui PIP. Untuk instruksi lebih lanjut, lihat README.md di direktori client .
Lihat lampiran untuk detail tentang cara menggunakan skrip testing_clients .
Cara terbaik untuk menjalankan VectorFlow adalah melalui docker compose . Jika Anda menjalankan ini di Mac, silakan berikan izin Docker untuk membaca dari folder dokumen Anda seperti yang diperintahkan di sini. Jika ini gagal, lepaskan bagian volume dari docker-compose.yml .
Pertama -tama buat folder, env_scripts , di root untuk semua variabel lingkungan, lalu buat env_vars.env di folder env_scripts untuk menambahkan semua variabel lingkungan yang disebutkan di bawah ini. Anda hanya perlu mengatur variabel LOCAL_VECTOR_DB jika Anda menjalankan qdrant, milvus atau weaviate secara lokal.
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
Anda dapat memilih variabel untuk INTERNAL_API_KEY , POSTGRES_PASSWORD , dan POSTGRES_DB , tetapi harus disetel.
Pastikan Anda menarik MQ Kelinci, Postgres, Min.io ke repo Docker lokal Anda. Kami juga merekomendasikan menjalankan vektor DB secara lokal, jadi pastikan untuk menarik gambar yang Anda gunakan. File docker-compose kami akan memutar Qdrant secara default dan membuat dua indeks/koleksi. Jika Anda berencana untuk menjalankan Milvus atau Weaviate, Anda harus mengonfigurasinya sendiri.
docker pull rabbitmq
docker pull postgres
docker pull qdrant/qdrant | docker pull semitechnologies/weaviate
docker pull minio/minio
Kemudian jalankan:
docker-compose build --no-cache
docker-compose up -d
Perhatikan bahwa wadah init menjalankan skrip yang mengatur skema basis data, vektor db dan store objek min.io. Wadah ini berhenti setelah skrip selesai. Untuk Qdrant, pastikan untuk menarik versi 1.9.1 karena itu adalah versi paket Python klien Qdrant seharusnya bekerja dengannya.
Cara terbaik untuk menggunakan VectorFlow adalah dengan klien Python.
Untuk menggunakan VectorFlow untuk pengembangan, buat permintaan HTTP ke URL API Anda - misalnya, localhost:8000 dari mesin pengembangan Anda, atau vectorflow_api:8000 dari dalam wadah Docker lain.
Semua permintaan memerlukan header HTTP dengan kunci Authorization yang sama dengan INTERNAL_API_KEY env Anda yang Anda tentukan sebelumnya (lihat di atas). Anda harus lulus tombol API database vektor Anda dengan header http X-VectorDB-Key jika Anda menjalankan penghubung ke instance berbasis cloud dari vektor db, dan kunci API embedding dengan X-EmbeddingAPI-Key jika Anda menggunakan openai . Embeddings transformator kalimat pelukan tidak memerlukan kunci API, tetapi Anda harus mengikuti langkah -langkah di atas untuk menjalankan wadah dengan model yang Anda butuhkan.
VectorFlow saat ini mendukung database vektor Pinecone, Qdrant dan Weaviate.
Untuk mengirimkan satu file untuk embedding, buat permintaan POST ke titik akhir /embed dengan file terlampir, header 'Content-Type: multipart/form-data' dan muatan berikut:
{
'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'
}
Ini akan menciptakan job dan Anda akan mendapatkan muatan berikut kembali:
{
'message': f"Successfully added {batch_count} batches to the queue",
'JobID': job_id
}
Saat ini titik akhir ini hanya mendukung pengunggahan file tunggal sekaligus, hingga 25 MB karena masalah waktu tunggu. Perhatikan bahwa itu mungkin sudah usang.
Untuk mengirimkan beberapa file untuk penyematan, buat permintaan POST ke titik akhir /jobs . Payload sama dengan untuk embedding file tunggal kecuali cara Anda melampirkan beberapa file berbeda:
{
'files=[
('file', ('test_pdf.pdf', open(file1_path, 'rb'), 'application/octet-stream')),
('file', ('test_medium_text.txt', open(file2_path, 'rb'), 'application/octet-stream'))
]'
}
Catatan: Anda harus stream file ke titik akhir, tidak mengirimkannya sebagai permintaan pos konvensional atau akan gagal.
Titik akhir ini akan membuat satu job per file yang diunggah. Anda akan mendapatkan payload JSON berikut:
{
'successful_uploads': successfully_uploaded_files,
'failed_uploads': failed_uploads,
'empty_files_count': empty_files_count,
'duplicate_files_count': duplicate_files_count
}
Di mana successfully_uploaded_files adalah daftar tupel yang berisi (file name, job id) dan failed_uploads adalah daftar nama file yang gagal mengunggah sehingga Anda dapat mencoba lagi.
Untuk memeriksa status job , buat permintaan GET titik akhir ini: /jobs/<int:job_id>/status . Responsnya akan ada dalam bentuk:
{
'JobStatus': job_status
}
Untuk memeriksa status job kelipatan, buat permintaan POST ke titik akhir ini: /jobs/status . Badan permintaan akan ada dalam formulir:
{
'JobIDs': job_ids
}
dan responsnya akan ada dalam formulir
{
'Jobs': [{'JobID': job_id, 'JobStatus': job_status}, ...]}
Ada contoh di testing_clients/get_jobs_by_ids.py .
VectorFlow menegakkan skema standar untuk mengunggah data ke toko vektor:
id: string
source_data: string
source_document: string
embeddings: float array
ID dapat digunakan untuk deduplikasi dan idempotensi. Harap dicatat untuk Weaviate, ID disebut vectorflow_id .
Kami merencanakan ini mencela ini di dekat Futuer untuk mendukung skema yang terdeteksi secara dinamis dan/atau yang dapat dikonfigurasi di ujung jalan.
VectorFlow's built in chunker dihitung dengan token bukan oleh karakter. chunk di VectorFlow adalah kamus yang memiliki kunci berikut:
text: str
vector: list[float]
Anda dapat menjalankan chunker khusus dengan menambahkan file, custom_chunker.py , dengan metode, chunker(source_data: list[str]) ke direktori src/worker sebelum membangun gambar Docker untuk pekerja. Chunker ini harus mengembalikan daftar kamus chunk yang sesuai dengan standar di atas.
Anda dapat menambahkan kunci apa pun yang Anda inginkan ke kamus chunk selama serializable JSON , yang berarti tidak ada kelas atau fungsi khusus, jenis datetimes atau referensi kode melingkar. Anda dapat menggunakan potongan khusus ini untuk kemudian mengunggah metadata ke vektor DB dengan skema apa pun yang Anda inginkan.
Jika Anda ingin menggunakan VectorFlow hanya untuk chunking dan menghasilkan embeddings, berikan parameter WebhookURL di badan permintaan /embed dan X-Webhook-Key sebagai header. VectorFlow mengasumsikan kunci webhook diperlukan untuk menulis kembali ke titik akhir apa pun. Embeddings dikirim kembali bersama dengan potongan sumber di kamus chunk yang diuraikan di atas. Ini dikirim sebagai JSON dengan bentuk berikut:
{
'Embeddings': list[dict],
'DocumentID': str,
'JobID': int
}
Jika Anda ingin memvalidasi potongan mana yang ingin Anda embed, lulus parameter ChunkValidationURL dalam tubuh permintaan /embed . Ini akan mengirim permintaan dengan payload JSON berikut, {"chunks": chunked_data} , di mana chunked_data adalah daftar kamus chunk . Ini akan diharapkan kembali JSON yang berisi kunci valid_chunks dengan daftar potongan yang valid untuk penyematan. Titik akhir ini akan batas waktu setelah 30 detik secara default tetapi dapat dikonfigurasi dalam kode aplikasi.
VectorFlow diintegrasikan dengan AWS S3. Anda dapat melewati URL S3 yang telah ditandatangani di tubuh HTTP alih-alih file. Gunakan bidang formulir PreSignedURL dan tekan titik akhir /s3 . Titik akhir ini memiliki konfigurasi dan batasan yang sama dengan titik akhir /embed .
VectorFlow menggunakan posthog untuk mengumpulkan data secara anonim tentang penggunaan. Ini tidak mengumpulkan informasi yang dapat diidentifikasi secara pribadi. Jika Anda ingin menonaktifkannya, tambahkan variabel lingkungan berikut ke env_vars.env Anda:
TELEMETRY_DISABLED=True
Anda dapat menjalankan vectorflow secara lokal di Kubernetes dengan minikube menggunakan ./kube/scripts/deploy-local-k8s.sh , yang akan menerapkan semua file YAML yang terletak di kube/ . Skrip ini tidak akan berfungsi jika Anda belum menginstal Docker, Minikube dan Kubectl.
Script ini pertama -tama akan membangun gambar secara lokal, kemudian mentransfernya ke Minikube. Jika Anda ingin memeriksa gambar apa yang tersedia di Minikube, jalankan yang berikut:
eval $(minikube docker-env)
docker images
Anda perlu menjalankan minikube tunnel untuk mengakses sumber daya yang terletak di cluster dari mesin pengembangan Anda. Skrip Pengaturan akan memuat gambar dari konteks Docker lokal Anda ke Minikube.
Anda dapat menggunakan file YAML di kube/ sebagai dasar untuk penyebaran produksi tetapi Anda perlu sedikit menyesuaikan dengan kebutuhan cluster spesifik Anda. Hubungi kami jika Anda membutuhkan bantuan.
Kami menyukai umpan balik dari komunitas. Jika Anda memiliki gagasan tentang cara membuat proyek ini lebih baik, kami mendorong Anda untuk membuka masalah atau bergabung dengan perselisihan kami. Tolong beri tag dgarnitz dan danmeier2 .
Peta jalan kami diuraikan di bagian di bawah ini dan kami akan senang membantu membangunnya. Masalah terbuka kami adalah tempat yang tepat untuk memulai dan dapat dilihat di sini. Jika Anda ingin mengerjakan sesuatu yang tidak terdaftar di sana, kami sarankan Anda membuka masalah dengan pendekatan yang diusulkan dalam pikiran sebelum mengirimkan PR.
Harap beri tag dgarnitz pada semua PR dan perbarui readme untuk mencerminkan perubahan Anda.
Saat mengirimkan PR, silakan tambahkan tes unit untuk menutupi fungsionalitas yang telah Anda tambahkan. Harap ikuti kembali tes yang ada untuk memastikan tidak ada bug regresif. Jalankan dari direktori src . Untuk menjalankan penggunaan tes individu:
python -m unittest module.tests.test_file.TestClass.test_method
Untuk menjalankan semua tes dalam penggunaan file:
python -m unittest module.tests.test_file
Untuk pengujian end-to-end, ini disarankan untuk membangun dan menjalankan menggunakan kompose Docker, tetapi kencangkan wadah yang Anda ubah dan jalankan secara lokal di mesin pengembangan Anda. Ini akan menghindari kebutuhan untuk terus membangun kembali gambar dan menjalankan kembali wadah. Pastikan untuk mengubah variabel lingkungan di terminal mesin pengembangan Anda ke nilai yang benar (yaitu localhost alih -alih rabbitmq atau postgres ) sehingga wadah Docker dapat berkomunikasi dengan mesin pengembangan Anda. Setelah bekerja secara lokal, Anda dapat melakukan tes akhir dengan segala sesuatu dalam komposisi Docker.
Harap verifikasi bahwa semua perubahan bekerja dengan komposisi Docker sebelum membuka PR.
Kami juga menyarankan Anda menambahkan bukti verifikasi, seperti tangkapan layar, yang menunjukkan bahwa kode Anda berfungsi dalam aliran ujung ke ujung.
Salah satu cara mudah untuk menggunakan VectorFlow adalah dengan klien pengujian kami, yang terletak di testing_clients/ direktori. Ada beberapa skrip, dengan konfigurasi yang berbeda untuk mengunggah data Qickly. Kami merekomendasikan mulai dengan testing_clients/standard_upload_client.py - Menjalankan skrip ini akan mengirimkan satu dokumen ke vectorflow untuk penyematan dengan AI ADA terbuka dan mengunggah ke instance QDrant lokal. Anda dapat mengubah nilai agar sesuai dengan konfigurasi Anda. Untuk mengunggah beberapa file sekaligus, gunakan testing_clients/streaming_upload_client.py
Perhatikan bahwa variabel TESTING_ENV adalah setara dengan bidang environment di VectorDBMetadata , yang sesuai dengan lingkungan di pincone, kelas di Weaviate, koleksi di Qdrant, dll. Direktori testing_clients memiliki skrip sampel yang dapat Anda ikuti untuk menjalankan flow vector. Tambahkan tombol embedding dan basis data Anda ke skrip env_scrips/env_vars.sh yang dihasilkan dan atur variabel filepath di testing_clients/standard_upload_client.py untuk menunjuk ke file yang ingin Anda embed. Kemudian jalankan:
source env_scrips/env_vars.sh
python testing-clients/standard_upload_client.py
Untuk mengunggah beberapa file sekaligus, gunakan testing_clients/streaming_upload_client.py
Lihat di atas untuk deskripsi yang lebih rinci tentang cara mengatur dan mengkonfigurasi sistem secara manual. Harap dicatat bahwa skrip setup tidak akan menciptakan lingkungan pengembangan di mesin Anda, itu hanya mengatur dan menjalankan komposisi Docker. Kami tidak menyarankan menggunakan VectorFlow di Windows.
Untuk melakukan pencarian, kirim permintaan POST ke /images/search titik akhir dengan file gambar terlampir, header 'Content-Type: multipart/form-data' dan badan berikut:
{
'ReturnVectors': boolean,
'TopK': integer, less than 1000,
'VectorDBMetadata={
"vector_db_type": "PINECONE | QDRANT | WEAVIATE",
"index_name": "index_name",
"environment": "env_name"
}'
}
Semua permintaan memerlukan header HTTP dengan kunci Authorization yang sama dengan INTERNAL_API_KEY env Anda yang Anda tentukan sebelumnya (lihat di atas). Anda harus lulus tombol API Vektor Database Anda dengan header HTTP X-VectorDB-Key jika Anda menjalankan penghubung ke instance berbasis cloud dari vektor DB.
Pencarian kesamaan gambar akan mengembalikan objek respons yang berisi kecocokan K atas, ditambah vektor mentah jika diminta, dengan formulir berikut:
{
"similar_images": list of match objects
"vectors": list of list of floats
}
di mana objek `match`` didefinisikan sebagai:
{
"id": str,
"score": float,
"metadata": {"source_document" : str}
}
Jika Anda ingin menggunakan docker build dan docker run untuk membangun dan menjalankan masing-masing gambar alih-alih docker-compose ikuti langkah-langkah ini:
cd src/docker build --file api/Dockerfile -t vectorflow_api:latest . untuk membangun - jangan lupa periode di akhirdocker run --network=vectorflow --name=vectorflow_api -d --env-file=../env_scripts/env_vars.env -p 8000:8000 vectorflow_api:latest untuk menjalankan API. Anda tidak perlu argumen port untuk menjalankan pekerja
