Model Profiles

Profiles are named bundles of runtime options. Instead of passing the same options repeatedly, define a profile once and reference it by name.

Quick Example

Python

from sie_sdk import SIEClient
from sie_sdk.types import Item

client = SIEClient("http://localhost:8080")

# Use the "sparse" profile
result = client.encode(
    "BAAI/bge-m3",
    Item(text="machine learning"),
    options={"profile": "sparse"}
)

# Returns sparse embeddings only
sparse = result["sparse"]
print(f"Non-zero tokens: {len(sparse['indices'])}")

TypeScript

import { SIEClient } from "@superlinked/sie-sdk";

const client = new SIEClient("http://localhost:8080");

// Use the "sparse" profile
const result = await client.encode(
  "BAAI/bge-m3",
  { text: "machine learning" },
  { options: { profile: "sparse" } } as never,
);

// Returns sparse embeddings only
const sparse = result.sparse;
console.log(`Non-zero tokens: ${sparse?.indices.length}`);

Built-in Profiles

Models can define multiple profiles. Common patterns include:

Profile	Purpose	Typical Settings
default	Standard behavior	Model’s default output types
sparse	Lexical search	output_types: [sparse]
muvera	ColBERT via dense	muvera: {}, output_types: [dense]

BGE-M3 includes sparse, banking, and medical-vn profiles. ColBERT models include muvera profiles for MUVERA-based retrieval.

Using Profiles

Pass the profile name in the options parameter:

Python

from sie_sdk import SIEClient
from sie_sdk.types import Item

client = SIEClient("http://localhost:8080")

# Sparse-only embedding
result = client.encode(
    "BAAI/bge-m3",
    Item(text="search query"),
    options={"profile": "sparse"}
)

# Domain-specific LoRA with custom instruction
result = client.encode(
    "BAAI/bge-m3",
    Item(text="transfer funds"),
    is_query=True,
    options={"profile": "banking"},
)

TypeScript

import { SIEClient } from "@superlinked/sie-sdk";

const client = new SIEClient("http://localhost:8080");

// Sparse-only embedding
let result = await client.encode(
  "BAAI/bge-m3",
  { text: "search query" },
  { options: { profile: "sparse" } } as never,
);

// Domain-specific LoRA with custom instruction
result = await client.encode(
  "BAAI/bge-m3",
  { text: "transfer funds" },
  { isQuery: true, options: { profile: "banking" } } as never,
);

The HTTP API uses the same options field:

curl -X POST http://localhost:8080/v1/encode/BAAI/bge-m3 \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"items": [{"text": "search query"}], "params": {"options": {"profile": "sparse"}}}'

Profile Fields

Profiles support these fields:

Field	Type	Description
extends	string	Inherit settings from another profile
adapter_path	string	Adapter class path (required unless extends)
max_batch_tokens	int	Maximum tokens per batch (required unless extends)
compute_precision	string	Precision override (float16, bfloat16, float32)
adapter_options	object	Nested loadtime and runtime option maps

Adapter Runtime Options

Behavior like output selection, instructions, and LoRA lives in adapter_options.runtime, not in top-level profile fields:

Option	Type	Description
output_types	list	Output types to return (dense, sparse, multivector)
output_similarity	dict	Similarity function per output type (cosine, dot)
instruction	string	Instruction prefix for queries
lora_id	string	LoRA adapter path (HuggingFace ID or local path)

Profiles can also include any other adapter-specific runtime options. For example, the muvera profile on ColBERT models includes muvera: {} to enable the postprocessor:

  muvera:
    extends: default
    adapter_options:
      runtime:
        muvera: {}
        output_types:
          - dense
        output_similarity:
          dense: cosine

Defining Custom Profiles

Define profiles in the model’s config YAML file:

sie_id: BAAI/bge-m3
hf_id: BAAI/bge-m3

profiles:
  default:
    max_batch_tokens: 16384
    adapter_path: sie_server.adapters.bge_m3_flash:BGEM3FlashAdapter
    adapter_options:
      runtime:
        pooling: cls
        normalize: true
  sparse:
    extends: default
    adapter_options:
      runtime:
        pooling: cls
        normalize: true
        output_types:
          - sparse
  banking:
    extends: default
    adapter_options:
      runtime:
        pooling: cls
        normalize: true
        lora_id: saivamshiatukuri/bge-m3-banking77-lora
        instruction: Classify banking intent

The profile named default is the default. A child profile’s non-empty adapter_options.runtime block fully replaces the parent’s, so repeat inherited keys like pooling and normalize.

Profile Resolution

Runtime options are resolved in two steps (later overrides earlier):

1. Profile - the selected profile’s resolved adapter_options.runtime: its own block if non-empty, otherwise the block from its extends parent. A profile without extends inherits nothing
2. Request - options passed in the request, merged on top key by key

# Request-level options override profile settings
result = client.encode(
    "BAAI/bge-m3",
    Item(text="query"),
    options={
        "profile": "sparse",
        "is_query": True  # Overrides any profile setting
    }
)

If no profile is specified, the default profile is used. If a profile name is invalid, the server returns an error listing available profiles.

Listing Available Profiles

Query the models endpoint to see available profiles:

curl http://localhost:8080/v1/models

The response includes profile information for each model.

What’s Next

• Sparse embeddings - when to use sparse output
• Multi-vector embeddings - MUVERA profile for ColBERT models