Skip to content

Embeddings

Before You Run Examples

All examples in this page assume environment variables are available. For convenience, create a .env file in the repository root (you can copy from .env.example) with:

TUDELFT_TULIP_BASE_URL=https://api.tulip.tudelft.nl
TUDELFT_TULIP_API_KEY=YOUR_API_KEY
TUDELFT_TULIP_MODEL_ALIAS=embed
TUDELFT_TULIP_CAPABILITY=embed

Set TUDELFT_TULIP_BASE_URL to host root only (for example https://api.tulip.tudelft.nl). The Python helper normalizes it to a capability-specific /v1 endpoint automatically.

What these examples assume

  • The Python snippets on this page assume a local helper file common.py that loads environment variables and exports shared constants.
  • If you cloned this repository, examples/common.py is already present and the scripts run as shown below.
  • If you have not cloned the repo and are working with Python, expand the helper snippet below and place common.py next to the example you want to run.
  • Python run commands use pixi run python ...; dependencies come from pixi.toml.
  • Bash examples pretty-print JSON using jq, so you may need to install it.
  • TUDELFT_TULIP_CAPABILITY chooses the path segment (embed).
  • TUDELFT_TULIP_MODEL_ALIAS chooses the deployed model alias.
If you have not cloned the repo and are working with Python, create common.py next to the example
common.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
import os

from dotenv import load_dotenv

load_dotenv()  # loads .env if present

TUDELFT_TULIP_BASE_URL = os.getenv(
    "TUDELFT_TULIP_BASE_URL", "https://api.tulip.tudelft.nl"
)
TUDELFT_TULIP_CAPABILITY = os.getenv("TUDELFT_TULIP_CAPABILITY", "chat")
TUDELFT_TULIP_API_KEY = os.getenv("TUDELFT_TULIP_API_KEY", "DUMMY_KEY")
TUDELFT_TULIP_MODEL_ALIAS = os.getenv("TUDELFT_TULIP_MODEL_ALIAS", "chat")

# Normalize TUDELFT_TULIP_BASE_URL to capability/v1. Docs recommend host root only,
# but we also accept URLs that already include capability or capability/v1.
_base_url = TUDELFT_TULIP_BASE_URL.rstrip("/")
if _base_url.endswith("/v1"):
    TUDELFT_TULIP_BASE_URL = _base_url
elif _base_url.endswith(f"/{TUDELFT_TULIP_CAPABILITY}"):
    TUDELFT_TULIP_BASE_URL = f"{_base_url}/v1"
else:
    TUDELFT_TULIP_BASE_URL = f"{_base_url}/{TUDELFT_TULIP_CAPABILITY}/v1"

Endpoint

Embeddings are available at /v1/embeddings. For more, seeOpenAI Embeddings API.

Supported Models

For available embedding models and the current model-to-alias mapping, see Model Alias Mapping.

Example Scripts

curl-embedding.sh
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
#!/bin/bash

set -o pipefail

SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
if [ -f "${SCRIPT_DIR}/../.env" ]; then
  source "${SCRIPT_DIR}/../.env"
fi

curl -sk --fail --show-error ${TUDELFT_TULIP_BASE_URL}/${TUDELFT_TULIP_CAPABILITY}/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TUDELFT_TULIP_API_KEY}" \
  -d '{"model":"'"$TUDELFT_TULIP_MODEL_ALIAS"'",
       "input":["Hello from tulip","this rocks!"],
       "encoding_format":"float"}' \
| jq '{n: (.data|length), dim: (.data[0].embedding|length)}'

curl -sk --fail --show-error ${TUDELFT_TULIP_BASE_URL}/${TUDELFT_TULIP_CAPABILITY}/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TUDELFT_TULIP_API_KEY}" \
  -d '{"model":"'"$TUDELFT_TULIP_MODEL_ALIAS"'",
       "input":["cat","quantum entanglement"],
       "encoding_format":"float"}' \
| jq '.data[].embedding[0:5]'
Run: 
bash examples/curl-embedding.sh

SDK: OpenAI Python client (OpenAI)

python_embedding.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
import sys

from common import (
    TUDELFT_TULIP_API_KEY,
    TUDELFT_TULIP_BASE_URL,
    TUDELFT_TULIP_MODEL_ALIAS,
)
from openai import OpenAI

print(f"Using base URL: {TUDELFT_TULIP_BASE_URL}", file=sys.stderr)
print(f"Using model alias: {TUDELFT_TULIP_MODEL_ALIAS}", file=sys.stderr)

client = OpenAI(base_url=TUDELFT_TULIP_BASE_URL, api_key=TUDELFT_TULIP_API_KEY)

print(
    "\n********** Check embeddings works (dimension check) *****************",
    file=sys.stderr,
)
response = client.embeddings.create(
    model=TUDELFT_TULIP_MODEL_ALIAS,
    input=["Hello from tulip", "this rocks!"],
    encoding_format="float",
)
print(f"Number of embeddings: {len(response.data)}")
print(f"Embedding dimension: {len(response.data[0].embedding)}")

print(
    "\n*** Check embeddings works (different strings -> different vectors) ***",
    file=sys.stderr,
)
response = client.embeddings.create(
    model=TUDELFT_TULIP_MODEL_ALIAS,
    input=["cat", "quantum entanglement"],
    encoding_format="float",
)
for item in response.data:
    print(f"Index {item.index}: {item.embedding[0:5]}")
Run: 
pixi run python examples/python_embedding.py

Success looks like

  • You receive embedding vectors for both input strings.
  • Reported embedding dimensions are consistent (e.g., 4096).
  • The two sample outputs are different vectors (first elements are not identical).