MESA Core · v0.9.3

Embedding ve model sağlayıcıları

v0.9.3 kaynak: docs/configuration.md

Bu rehberin Türkçe ve İngilizce sürümleri aynı konuyu açıklar. Bu sayfayla ilgili kaynak bölümleri en altta yer alır.

Desteklenen sağlayıcılar#

GörevSağlayıcı değeriÖrnek modelBoyutKurulum eki
Embedding · yerel (varsayılan)sentence-transformersBAAI/bge-m3, normalize1024ml
Embedding · hariciopenai_compatibletext-embedding-3-small1536temel paket
Embedding · Nemotron-3 profiliopenai_compatibleNemotron-3, nemotron-qpass-v1 (sorgu/pasaj)2048temel paket
Çıkarım / doğrulama LLMopenai_compatibleuç noktanızın sunduğu bir sohbet modeli, örn. gpt-4o-mini—temel paket
Çıkarım / doğrulama LLMclaudebir Claude modeli—[adapters]
Çıkarım / doğrulama LLMollamaçalışan Ollama’da önceden indirilmiş model—temel paket
Yalnızca testmockbilgi döndürmez——

Çıkarım ve embedding ayrı yapılandırılır: çıkarım için claude veya ollama seçmek embedding’i kurmaz. auto gerektiğinde mock’a düşebilir; sağlayıcıyı açıkça belirtin. Sağlayıcı, model, boyut veya normalizasyon değişince yeni bir embedding alanı başlar; yeniden indeksleme veya yeni depolama kökü gerekir.

Belge ve sorgu temsilleri uyumlu olmalı#

Bilgi kayıtlarının vektörleri ile sorgu vektörleri aynı sağlayıcı/model kimliğini ve boyutları kullanmalıdır. Belgelenen yerel varsayılan local:BAAI/bge-m3, 1024 boyutludur; dış sağlayıcıdaki text-embedding-3-small ise 1536 boyut kullanır. Ayarı değiştirmek eski verileri dönüştürmez. Model değiştirirken belgelenen kimlik kurallarına göre arama görünümünü ve indeksi yeniden oluşturun.

Ayarın bulunması, sağlayıcının çalıştığını göstermez#

GET /v4/capability, o anda kullanılabilen özellikleri bildirir. Özel bir sayısal temsil sağlayıcısı, ilk başarılı çağrıdan önce çalışır kabul edilmez. Beklenen vektör veya sağlayıcı hatalarında açık bir 503 yanıtı verilir; sistem sessizce başka modele geçmez. V4 combined tüketici, modeller kapalıyken de veri alır ve BM25 araması sağlar; çıkarım ve sayısal temsil sağlayıcılarını gerektiğinde açın.

Dış erişimi ayrıca değerlendirin#

MESA_EXTERNAL_PROVIDER_ENABLED=false, asıl işleme hattındaki dış sağlayıcı çağrılarını sınırlar. Bu ayar tek başına sistemin tamamen ağdan yalıtıldığını veya hiç ücret doğurmayacağını garanti etmez. Model indirmeleri ve başka süreçlerin ağ erişimi ayrıca değerlendirilmelidir. v0.9.1 DEV benchmark’ı, belirtilen koşullarda BGE arama kalitesini ve donanım gecikmesini raporlar; bulut sağlayıcısının token maliyetini ölçmez.

v0.9.3 ile çalışma#

MESA_LLM_MODEL=provider:model ve MESA_EMBEDDING_MODEL=provider:model kullanın. Modeller kapalıyken BM25 veri alımı/araması çalışır. Dış sağlayıcı bayrağı kapalıyken yerel Ollama ve OpenAI uyumlu uç noktalar kullanılabilir; bulut sağlayıcıları açık bayrak ve anahtar ister.

Kaynak belgedeki ilgili bölümler

Bu bölüm, kaynak belgenin bu sayfayla ilgili kısımlarını değiştirmeden gösterir. Kaynak içindeki bir bölüme giden bağlantıyı açtığınızda metin otomatik olarak görünür.

Providers and capacity#

MESA_CHUNKING=auto (default) splits new document revisions at Turkish article

headings when at least three occur at line starts. The preamble stays separate;

long articles use the existing paragraph/sentence splitting with a 512-token

limit. All slices preserve the exact source text. Other documents keep the same

plain chunks; MESA_CHUNKING=plain selects that plan for every document. Retrying

a pending upload preserves the plan matching its already admitted chunk texts,

even after restarting or changing this setting. Active revisions are unchanged.

If an admitted prefix fits two different plans, the retry returns 409 without

appending chunks, because the stored text cannot identify the original plan.

MESA_LEGAL_RULES_ENABLED=true enables Turkish legal rule processing. In auto

chunking mode, ordinary article chunks inherit the document's law number from

metadata.law_number or a Kanun Numarası, Kanunun Numarası or Kanun No.

header in the first 3,000 characters. Continuation pieces keep that article's

identity; preambles, GEÇİCİ/EK articles and plain plans receive none. Setting the

switch to false disables automatic identity assignment for new chunks. It also

disables legal processing during search, including citation resolution, the

exact-match slot, decision künye promotion, legal ranking factors and graph

citation parsing. Ordinary lexical, vector and graph retrieval still run.

Search ignores stored legal identities and item snapshots while the switch is

off and omits their legal result annotations; it does not erase them. Stored

identities are immutable on resume. Any 3–5 digit law number is accepted by the

typed identity API; known numbers retain their existing statute code (6098 →

TBK). Unknown law names and inconsistent number/code pairs are rejected.

Numbered queries such as 7201 sayılı Kanunun 21. maddesi use the existing

typed legal candidate lane and ranking factors. Document fallback assertions

keep their document subject, madde relation and chunk object; automatic

article identity changes only the typed columns.

Newly admitted chunks also keep versioned citation, decision-reference, date,

amount, duration and outcome items. Search returns them in

retrieval_provenance.legal_items as {version, items}. Item start/end

offsets refer to the original chunk, including when a result quotes a shorter

extracted fact. Items remain separate from SPO facts and do not enter fusion

scores. Decision references can use the bounded exact-match slot below.

Disabling the switch prevents new item snapshots and hides existing snapshots

from search results. Existing snapshots remain stored. Purging a document

erases these source quotes too.

An exact law-and-article query puts at most three matching chunks first, in

document order. Other results retain their fused order (or reranked order when

reranking is enabled). The match must exist in the authorized search scope.

A query's docket and decision numbers can also match a decision's own künye:

a stored decision_ref starting within the first 300 characters of chunk zero.

Its first chunk shares the same three-chunk limit with article matches, in

document order. Later quotations do not teach a decision's identity. The map

uses the same tenant, dataset, agent and time scope cache as law names; an

unmatched reference leaves result order unchanged.

The scope cache learns law names from titles and first-chunk law headers of

documents with trusted article identities; it never learns them from another

tenant, dataset, agent or time scope. Names accept case and Turkish ı/i variants,

possessive suffixes, and K. for Kanunu. The longest exact name from that scope

takes precedence over an overlapping ontology alias. Ambiguous store names

shared by different law numbers are ignored. No static law-name table is added.

MESA_RERANK_ENABLED=false keeps the existing fused ranking and does not import

ML packages. Enabling it requires pip install "mesa-memory[ml]"; startup checks

that the package is installed, and the model loads lazily on the first search.

MESA_RERANK_MODEL defaults to BAAI/bge-reranker-v2-m3 (Apache-2.0), with

MESA_RERANK_DEPTH=50 (range 1–50). The scorer uses authorized full chunk texts

after releasing the search connection, in a worker thread, then returns the

requested number of results. Tied scores retain fused order. Results keep their

fusion fields, including rrf_score and final_score, and add rerank_score.

The first search includes model-load latency; subsequent searches reuse it.

Model and external-provider flags default false. Validation defaults to

mode 0; mode 1 or 2 must be set explicitly via MESA_TIER3_MODE. Mode 2

needs distinct A/B validator identities. Extraction and validation are separate.

MESA_EMBEDDING_ENABLED defaults to MESA_MODEL_ENABLED; MESA_EXTRACTION_ENABLED

defaults to false (D46). A combined runtime accepts writes with both off and finds

them through BM25. Disabled VECTOR lanes end SKIPPED; enabling embedding later

backfills them at startup using the same embedding identity. Backfill failures

leave committed records searchable.

MESA_GRAPH_ENABLED defaults to true, independently of the model flags.

Set it to false to avoid opening Kùzu in the runtime and offline rebuild

runner. GRAPH lanes end SKIPPED, BM25 and enabled vector search still work,

search reports graph in degraded_sources, and capability reports no graph.

Enabling it again backfills skipped GRAPH lanes at combined startup. A rebuild

with graph disabled also marks previously completed GRAPH lanes SKIPPED at

cutover so the new generation can be backfilled later. Existing graph files and

retained generations are not erased by changing this flag.

Local identity defaults to BAAI/bge-m3 1024-d normalized (upgraded from

local:magibu/embeddingmagibu-200m 768-d; existing stores created before v0.9.3 must keep

MESA_EMBEDDING_MODEL=local:magibu/embeddingmagibu-200m and MESA_EMBEDDING_DIMENSION=768

unless rebuilt); external text-embedding-3-small

requires setting dimension to 1536. Do not enable external flag and keep an

unrelated dimension. Nemotron-3 profile requires 2048 and nemotron-qpass-v1,

with query/passage input types. Provider/model/revision/dimension/normalization

define a fenced embedding space; switch through reindex/rebuild, not live fallback.

Install optional ML/provider SDK extras for the selected backend. With models

disabled semantic generation is intentionally unavailable. MESA_ZERO_COST_MODE

selects local Ollama configuration but preserves validator settings and does

not prove an air gap. RAM budget precedence is explicit MAX_RAM_MB/MAX_MEMORY_BYTES,

cgroups, psutil, then 1 GiB safe fallback; this is not an RSS guarantee.

Queue per-tenant bounds must fit within global bounds. .env.example deliberately

uses smaller sample global and per-tenant bounds than code defaults.

Minimal V4 provider setup#

Start with the disposable root, key and grants from the

quickstart, with the server stopped.

For an external OpenAI-compatible extraction + embedding setup, install

uv sync --locked --python 3.11 --extra adapters (no local ML extra is needed).

Select models supported by your endpoint. The following is an example pairing,

not evidence of a real-provider run:

bash
mkdir -p "$HOME/mesa-doc-demos"
export MESA_STORAGE_ROOT="$(mktemp -d "$HOME/mesa-doc-demos/v4-XXXXXX")"
export MESA_PRINCIPAL_ID=docs-principal
export MESA_API_KEY="$(.venv/bin/mesa-v4-admin issue-key --principal docs-principal)"
.venv/bin/mesa-v4-admin grant-role --principal docs-principal --tenant docs-tenant --role OWNER
.venv/bin/mesa-v4-admin grant-agent --principal docs-principal --agent docs-agent --permission SESSION_CREATE
export MESA_RUNTIME_PROFILE=combined
export MESA_LOAD_DOTENV=false
export MESA_MODEL_ENABLED=true
export MESA_EXTERNAL_PROVIDER_ENABLED=true
export MESA_TIER3_MODE=0
export MESA_LLM_MODEL=openai:gpt-4o-mini
export MESA_LLM_API_KEY="${OPENAI_API_KEY:?Supply the provider key privately first}"
export MESA_EMBEDDING_MODEL=openai:text-embedding-3-small
export MESA_EMBEDDING_BASE_URL=https://api.openai.com/v1
export MESA_EMBEDDING_API_KEY="$MESA_LLM_API_KEY"
export MESA_EMBEDDING_DIMENSION=1536
export MESA_EMBEDDING_NORMALIZED=true
export MESA_EMBEDDING_VERSION=v1

A root without active vector artifacts adopts a changed embedding identity at

startup and backfills skipped VECTOR lanes. A root with active vectors requires

an explicit rebuild before changing identity. Keep MESA_API_KEY (MESA access) separate

from MESA_LLM_API_KEY / MESA_EMBEDDING_API_KEY (provider access). Modes 1/2 need

the validator A or A/B settings from the table below. Extraction is configured

separately and mode 0 still calls it.

AdapterFactory parses provider:model (ollama, openai, openai_compatible,

anthropic, mock). Embeddings support local sentence-transformers (ml extra) or

OpenAI-compatible endpoints (adapters extra); Claude/Ollama extraction does not

automatically configure embeddings. Native Ollama extraction requires a running

endpoint and an already available model; MESA does not provision it.

Select embeddings with MESA_EMBEDDING_MODEL=provider:model: local:...,

ollama:qwen3-embedding:4b, openai:text-embedding-3-small, or

openai_compatible:nvidia/nemotron-3-embed-1b. The second colon stays in the

model name. MESA_EMBEDDING_BASE_URL overrides the endpoint; Ollama otherwise

uses <MESA_OLLAMA_URL>/v1 and needs no key for a local server.

Local model servers and external providers (D31)#

An endpoint is considered local when its scheme is http or https and its host is localhost, 127.0.0.1, ::1, or host.docker.internal.

  • With MESA_EXTERNAL_PROVIDER_ENABLED=false (default):
  • ollama and openai_compatible (for both LLM extraction and embedding) are allowed on local endpoints (e.g. Ollama on 127.0.0.1:11434, or vLLM on 127.0.0.1:8001/v1; MESA itself uses port 8000) and forbidden on non-local/remote endpoints.
  • openai_compatible on a local endpoint requires no API key (the client sends local automatically).
  • External cloud providers (openai, claude, anthropic, hosted) remain strictly forbidden regardless of endpoint URL.
  • With MESA_EXTERNAL_PROVIDER_ENABLED=true:
  • Remote and cloud provider endpoints are allowed. Cloud providers and remote

openai_compatible endpoints require configured API keys (MESA_LLM_API_KEY,

MESA_EMBEDDING_API_KEY); local openai_compatible endpoints still default

to local, and Ollama keeps its existing key-free behavior.

Missing optional packages (P5-01)#

If an optional provider or model extra is selected but not installed, server startup halts with a clear one-line installation command:

  • Ollama LLM, Ollama embedding, or OpenAI-compatible embedding:

pip install mesa-memory

  • Local transformer embedding (sentence-transformers):

pip install "mesa-memory[ml]"

Endpoint/key settings retain the MESA_LLM_BASE_URL / MESA_LLM_API_KEY fallbacks for those providers.

With embedding enabled and MESA_EMBEDDING_DIMENSION unset, the server and

rebuild runner embed one probe at startup and use its length for storage and

admission. Probe failure stops startup and names the model and URL. Setting the

dimension explicitly skips the probe; embedding disabled with no dimension

keeps 1024 and makes no embedding requests. The removed embedding provider,

external-model and local-model variables stop runtime startup with the

replacement setting. Nemotron still requires MESA_EMBEDDING_VERSION=nemotron-qpass-v1

and 2048 dimensions (explicit or detected).

The built-in mock adapter returns no extracted facts; it is not a source-backed

V4 demo. Contract tests inject deterministic fact and embedding providers

explicitly. Models-disabled startup, deterministic V4 tests and real-provider

V4 runs are different verification levels. V3 raw-memory processing requires

embeddings too; models-disabled boot does not demonstrate insert/search success.