Christoph Haas
111af2d66e
All checks were successful
Build and push container image / build-and-push (push) Successful in 4m10s
Replace all-MiniLM-L6-v2 with bge-small-en-v1.5, which separates short search queries from package descriptions via the retrieval instruction. Requests now default to query mode and opt out with type=passage for documents. Uses the export's pooled, L2-normalized sentence_embedding output instead of manual mean pooling.
64 lines
1.8 KiB
Markdown
64 lines
1.8 KiB
Markdown
# Vector Service
|
|
|
|
A minimal Go container that provides text embedding vectors using the
|
|
[bge-small-en-v1.5](https://huggingface.co/BAAI/bge-small-en-v1.5) model
|
|
(384 dimensions). The service accepts POST requests and returns an embedding
|
|
vector, ready to be consumed by pgvector.
|
|
|
|
## Model
|
|
|
|
bge-small-en-v1.5 uses **asymmetric** embeddings: queries and passages are
|
|
embedded differently, which is what lets a short search query align with a
|
|
package description. To support this, the request carries a `type`:
|
|
|
|
- **default (omitted)** — treated as a **query**: the text is prefixed with
|
|
the bge retrieval instruction
|
|
(`Represent this sentence for searching relevant passages: `). This keeps
|
|
existing callers that send a bare `{"text": ...}` working unchanged.
|
|
- `"passage"` — embedded as-is (used for documents/descriptions).
|
|
|
|
## API
|
|
|
|
`POST /vector`
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8080/vector \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"text": "sqlite editor", "type": "query"}'
|
|
```
|
|
|
|
```json
|
|
{ "vector": [0.023, -0.118, ...] }
|
|
```
|
|
|
|
Endpoints:
|
|
|
|
- `POST /vector` — embed text.
|
|
- `GET /ok` — health check.
|
|
- `GET /version` — build revision.
|
|
|
|
Optional Bearer auth via the `API_SECRET` environment variable.
|
|
|
|
## Build
|
|
|
|
```bash
|
|
docker build -t vector-service .
|
|
```
|
|
|
|
The build downloads the pre-converted ONNX model
|
|
(`onnx-community/bge-small-en-v1.5-ONNX`) and the ONNX Runtime shared library,
|
|
then compiles the Go binary.
|
|
|
|
## Run
|
|
|
|
```bash
|
|
docker run --rm -p 8080:8080 -e API_SECRET=your-secret-key vector-service
|
|
```
|
|
|
|
## Technical details
|
|
|
|
- **Model**: bge-small-en-v1.5 (ONNX), 384 dimensions
|
|
- **Pooling/normalization**: the export's `sentence_embedding` output is
|
|
mean-pooled and L2-normalized
|
|
- **Runtime**: Go + ONNX Runtime (no Python)
|
|
- **Files**: `main.go` (server), `Dockerfile`
|