MESA Core · v0.9.3
Embedding ve model sağlayıcıları
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örev | Sağlayıcı değeri | Örnek model | Boyut | Kurulum eki |
|---|---|---|---|---|
| Embedding · yerel (varsayılan) | sentence-transformers | BAAI/bge-m3, normalize | 1024 | ml |
| Embedding · harici | openai_compatible | text-embedding-3-small | 1536 | temel paket |
| Embedding · Nemotron-3 profili | openai_compatible | Nemotron-3, nemotron-qpass-v1 (sorgu/pasaj) | 2048 | temel paket |
| Çıkarım / doğrulama LLM | openai_compatible | uç noktanızın sunduğu bir sohbet modeli, örn. gpt-4o-mini | — | temel paket |
| Çıkarım / doğrulama LLM | claude | bir Claude modeli | — | [adapters] |
| Çıkarım / doğrulama LLM | ollama | çalışan Ollama’da önceden indirilmiş model | — | temel paket |
| Yalnızca test | mock | bilgi 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:
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=v1A 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): ollamaandopenai_compatible(for both LLM extraction and embedding) are allowed on local endpoints (e.g. Ollama on127.0.0.1:11434, or vLLM on127.0.0.1:8001/v1; MESA itself uses port 8000) and forbidden on non-local/remote endpoints.openai_compatibleon a local endpoint requires no API key (the client sendslocalautomatically).- 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.
