README.md

English | 中文

Visual management tool for the Zvec embedded vector database
Browse data, test queries, and manage schemas — without writing code.

---

📦 Installation

Option 1: pip (recommended for developers)

Requires Python 3.10 – 3.14.

pip install zvec-studio
zvec-studio

Opens http://127.0.0.1:7860 in your browser.

Need embedding & reranking? Install with the [ai] extra to enable built-in embedding & reranking functions:

pip install zvec-studio[ai]

Option 2: Desktop download (experimental)

Grab the installer for your platform from GitHub Releases:

Platform	Architectures	Installer
macOS	Apple Silicon (arm64)	.dmg
Linux	x86_64, arm64	.deb / .AppImage
Windows	x86_64	.msi / .exe

Double-click to run — no Python needed.

Option 3: From source

git clone https://github.com/zvec-ai/zvec-studio.git
cd zvec-studio
make install    # install Node deps + backend uv environment
make dev        # starts backend + frontend dev servers

Need embedding & reranking? make install does NOT install AI runtime dependencies (sentence-transformers, dashscope, etc.) to keep CI fast. Run make install.ai instead if you want to use built-in functions like local-dense, bm25, or dashscope.

Prerequisites: Node.js ≥ 20, pnpm ≥ 9, Python ≥ 3.10, uv, Rust (desktop only). See Contributing for the full dev setup guide.

⚡ Quick Start

1. Create a collection — Collections → Create. Define vector and scalar fields.
2. Insert data — Paste JSON documents in the Write tab.
3. Vector search — Paste a query vector in the Query tab, set TopK, hit Search.
4. AI search — Register an embedding model, then search by typing text directly.

Full walkthrough → Getting Started

📖 Documentation

Getting Started	10-minute walkthrough from install to first search
Architecture	Request flow, module map, code index
API Reference	REST endpoints, request/response formats, error codes
Testing	Test strategy, self-verification loop, performance baselines
Packaging	PyInstaller + Tauri cross-platform packaging
Contributing	Dev setup, code style, commit workflow

🗺️ Roadmap

Version	Focus
v0.1.x (current)	Collection CRUD, schema evolution, document ops, vector search, AI extension, i18n, desktop app
v0.2.x	Data import/export, virtual scrolling, batch operations, advanced search
v0.3.x	Vector visualization (UMAP/t-SNE), clustering, AI Agent, SDK code generation
v0.4.x	VS Code extension, API Playground, webhooks & notifications

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for details.

make dev        # Start dev servers
make verify     # Lint + typecheck + tests

📄 License

Apache License 2.0