126 lines
3.0 KiB
Markdown
126 lines
3.0 KiB
Markdown
# Embedd HUB
|
|
|
|
Embedd HUB is a local-first Laravel workbench for exploring text embeddings. It lets users generate vectors, search similar stored phrases, and compare phrase proximity with Ollama and PostgreSQL vector storage.
|
|
|
|
## Features
|
|
|
|
- Generate embeddings for words, phrases, or multiline text.
|
|
- Store vectors in PostgreSQL with vector indexes when using pgvector.
|
|
- Search existing embeddings by semantic similarity.
|
|
- Compare multiple phrases with a pairwise similarity matrix and ranked pairs.
|
|
- Pick embedding models from the live Ollama `/api/tags` response.
|
|
- Show clear Ollama online/offline status before running embedding actions.
|
|
- Track per-user usage on the dashboard.
|
|
|
|
## Stack
|
|
|
|
- Laravel 13
|
|
- Livewire 4 single-file components
|
|
- Flux UI 2
|
|
- Laravel AI SDK
|
|
- PostgreSQL with vector storage
|
|
- Ollama for local embedding generation
|
|
- Tailwind CSS 4 and Vite
|
|
- Pest 4
|
|
|
|
## Requirements
|
|
|
|
- PHP 8.4
|
|
- Composer
|
|
- Node.js and npm
|
|
- PostgreSQL 18 or another PostgreSQL version with vector extension support
|
|
- Ollama running locally or on a reachable host
|
|
|
|
## Setup
|
|
|
|
Install PHP and JavaScript dependencies:
|
|
|
|
```bash
|
|
composer install
|
|
npm install
|
|
```
|
|
|
|
Create the environment file and app key:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
php artisan key:generate
|
|
```
|
|
|
|
Configure PostgreSQL in `.env`:
|
|
|
|
```dotenv
|
|
DB_CONNECTION=pgsql
|
|
DB_HOST=127.0.0.1
|
|
DB_PORT=5432
|
|
DB_DATABASE=embedd_hub
|
|
DB_USERNAME=postgres
|
|
DB_PASSWORD=
|
|
```
|
|
|
|
Configure Ollama:
|
|
|
|
```dotenv
|
|
OLLAMA_URL=http://localhost:11434
|
|
OLLAMA_EMBEDDINGS_DIMENSIONS=768
|
|
```
|
|
|
|
The dimensions must match the embedding model you plan to use. Set this before running migrations so the vector column is created with the correct size.
|
|
|
|
Run migrations and build assets:
|
|
|
|
```bash
|
|
php artisan migrate
|
|
npm run build
|
|
```
|
|
|
|
## Ollama
|
|
|
|
Start Ollama and pull at least one embedding-capable model:
|
|
|
|
```bash
|
|
ollama serve
|
|
ollama pull nomic-embed-text
|
|
```
|
|
|
|
Embedd HUB does not use a configured default model. The tool pages call the Ollama API and list the models returned from `/api/tags`. If Ollama cannot return that model list, embedding actions are disabled and the UI shows an offline status.
|
|
|
|
## Development
|
|
|
|
For Laravel Herd, the app is available at:
|
|
|
|
```text
|
|
https://embedd-hub.test
|
|
```
|
|
|
|
Common commands:
|
|
|
|
```bash
|
|
npm run dev
|
|
php artisan test --compact
|
|
vendor/bin/pint --dirty --format agent
|
|
```
|
|
|
|
## Project Map
|
|
|
|
- `app/Services/EmbeddingWorkbench.php` - embedding generation, search, comparison, and Ollama model discovery.
|
|
- `app/Concerns/InteractsWithEmbeddingWorkbench.php` - shared Livewire state for model selection and availability.
|
|
- `resources/views/pages/embeddings` - the Embed, Search, and Compare pages.
|
|
- `resources/views/dashboard.blade.php` - usage dashboard.
|
|
- `database/migrations/*embedding*` - vector storage and usage event tables.
|
|
- `public/favicon.svg` - source SVG favicon asset. It is intentionally not referenced in templates.
|
|
|
|
## Testing
|
|
|
|
Run the full suite:
|
|
|
|
```bash
|
|
php artisan test --compact
|
|
```
|
|
|
|
Run only embedding tool tests:
|
|
|
|
```bash
|
|
php artisan test --compact tests/Feature/EmbeddingToolsTest.php
|
|
```
|