Embedding-API-Vertrag und Servicegrenze festlegen #7

New issue

Closed

opened 2026-08-10 13:40:05 +02:00 by zwuge · 1 comment

zwuge commented

2026-08-10 13:40:05 +02:00

Owner

Question

Welcher minimale, stabile HTTP-Vertrag und welche Servicegrenze werden im dgx-spark-Repo implementiert, damit secondbrain-mcp Embeddings anfordern kann, ohne Qwen- oder Backfill-Logik in diesen Dienst zu verschieben?

Parent map: Wayfinder: Embedding-Schnittstelle neben Qwen im DGX Spark

Starting assumptions

Die bestätigten Wayfinder-Empfehlungen gelten als Ausgangspunkt: separater Dienst neben Qwen, nomic zuerst, kleiner /embed-Vertrag, Sicherheits- und Live-Verifikationsziel.

## Question Welcher minimale, stabile HTTP-Vertrag und welche Servicegrenze werden im dgx-spark-Repo implementiert, damit secondbrain-mcp Embeddings anfordern kann, ohne Qwen- oder Backfill-Logik in diesen Dienst zu verschieben? Parent map: [Wayfinder: Embedding-Schnittstelle neben Qwen im DGX Spark](https://git.platz-consulting.de/zwuge/dgx-spark/issues/6) ## Starting assumptions Die bestätigten Wayfinder-Empfehlungen gelten als Ausgangspunkt: separater Dienst neben Qwen, nomic zuerst, kleiner /embed-Vertrag, Sicherheits- und Live-Verifikationsziel.

zwuge added the

wayfinder:grilling

label

2026-08-10 13:40:05 +02:00

zwuge added a new dependency

2026-08-10 13:40:06 +02:00

#10 Embedding-Endpunkt absichern und deploybar machen

zwuge added a new dependency

2026-08-10 13:40:06 +02:00

#11 Embedding-Schnittstelle gegen secondbrain-mcp live verifizieren

zwuge self-assigned this

2026-08-10 14:28:38 +02:00

zwuge commented

2026-08-10 14:37:37 +02:00

Author

Owner

Resolution

Der Vertrag wird als kleiner, stabiler HTTP-Vertrag festgelegt:

POST /embedn- Request: model, ask, extsn- ask verwendet die semantischen Werte search_document oder search_query ohne Doppelpunkt; der Spark-Service ergänzt den modellabhängigen Präfix intern.
model ist Pflichtfeld und wird ausschließlich gegen das serverseitig konfigurierte Modell geprüft; keine freie Modellwahl durch den Client.
Response: model und mbeddings; genau ein Vektor je Eingabetext.
Ungültige Requests liefern 4xx, Rate-Limit 429, temporäre Runtime-/Ressourcenprobleme 5xx.
Retry, Backoff und Job-Queue bleiben vollständig bei secondbrain-mcp; der Spark-Service verarbeitet einzelne synchrone Requests.
Keine Notiz-/Querytexte in Response-Diagnostik oder Logs.

Damit ist die Servicegrenze zwischen Spark-Embedding-Service und secondbrain-mcp entschieden. Umsetzung und Live-Verifikation bleiben nachgelagerte Tickets.

## Resolution Der Vertrag wird als kleiner, stabiler HTTP-Vertrag festgelegt: - POST /embed`n- Request: model, ask, exts`n- ask verwendet die semantischen Werte search_document oder search_query ohne Doppelpunkt; der Spark-Service ergänzt den modellabhängigen Präfix intern. - model ist Pflichtfeld und wird ausschließlich gegen das serverseitig konfigurierte Modell geprüft; keine freie Modellwahl durch den Client. - Response: model und mbeddings; genau ein Vektor je Eingabetext. - Ungültige Requests liefern 4xx, Rate-Limit 429, temporäre Runtime-/Ressourcenprobleme 5xx. - Retry, Backoff und Job-Queue bleiben vollständig bei secondbrain-mcp; der Spark-Service verarbeitet einzelne synchrone Requests. - Keine Notiz-/Querytexte in Response-Diagnostik oder Logs. Damit ist die Servicegrenze zwischen Spark-Embedding-Service und secondbrain-mcp entschieden. Umsetzung und Live-Verifikation bleiben nachgelagerte Tickets.

zwuge closed this issue

2026-08-10 14:37:37 +02:00