AI Knowledge Base ve LLM Gateway Service API Referansı

AI KNOWLEDGE SERVICE (/api/knowledge)

KnowledgeController — /api/knowledge

#	Method	Route	Auth	Description
1	GET	/api/knowledge?page={int}&pageSize={int}	Required	Knowledge base listesi (PaginatedList<KnowledgeBaseDto>)
2	POST	/api/knowledge	Required	Yeni KB oluştur — 201 Created (CreateKnowledgeBaseCommand: name, description, embeddingBackendId, embeddingModelId)
3	GET	/api/knowledge/{kbId:guid}	Required	KB detayı (KnowledgeBaseDetailDto — chunk sayısı, embedding bilgisi)
4	PUT	/api/knowledge/{kbId:guid}	Required	KB güncelle
5	DELETE	/api/knowledge/{kbId:guid}	Required	KB sil (soft delete)

Knowledge Base Chunk Endpoints

#	Method	Route	Auth	Description
6	POST	/api/knowledge/{kbId}/documents/upload	Required	Belgeleri yükle ve vektörize et — 202 Accepted (multipart/form-data: PDF, DOCX, TXT, Markdown)
7	GET	/api/knowledge/{kbId}/documents?page={int}&pageSize={int}	Required	Yüklenen belgeler listesi (PaginatedList<DocumentDto>)
8	DELETE	/api/knowledge/{kbId}/documents/{documentId:guid}	Required	Belge sil

Semantic Search

#	Method	Route	Auth	Description
9	POST	/api/knowledge/{kbId}/search	Required	Semantik arama — 200 OK (SearchQueryCommand: query, topK=5, similarityThreshold=0.75)

Response:

{
  "success": true,
  "result": {
    "chunks": [{
      "text": "string",
      "score": 0.92,
      "sourceDocumentName": "string",
      "startLine": 42,
      "endLine": 58
    }],
    "totalResults": 5
  }
}

Internal Knowledge Controller — internal routing

#	Method	Route	Auth	Description
10	GET	/api/knowledge/internal/{kbId:guid}/embedding-info	InternalAPI Key	Embedding backend bilgisi (RAG için)

---

AI LLM GATEWAY (/api/llm-gateway)

LlmGatewayController — public-facing proxy

#	Method	Route	Auth	Description
1	POST	/api/llm-gateway/completions	Required	Completion proxy (routing yapar) — 200 OK (ApiResponse<CompletionResponseDto>)
2	POST	/api/llm-gateway/embeddings	Required	Embedding proxy — 200 OK (ApiResponse<EmbeddingResponseDto>)

Gateway Request Body

{
  "model": "string (optional, if null: auto-select based on routing strategy)",
  "messages": [
    { "role": "system|user|assistant", "content": "string" }
  ],
  "temperature": 0.7,
  "maxTokens": 4096,
  "routingStrategy": "cost | latency | quality | manual (optional)",
  "budgetLimit": 100.0,
  "allowedModels": ["string[]"],
  "semanticCacheKey": "string | null"
}

Gateway Response Body

{
  "success": true,
  "result": {
    "responseText": "string",
    "modelUsed": "string (e.g., gpt-4o-mini)",
    "backendUsed": "string (e.g., ollama-local)",
    "tokenUsage": { "promptTokens": 128, "completionTokens": 256, "totalTokens": 384 },
    "latencyMs": 450,
    "cached": false,
    "fallbackChain": ["openrouter", "ollama-macstudio"]
  }
}

Routing Strategy Enum

Value	Name	Description
0	CostOptimize	En ucuz model seç
1	LatencyOptimize	En hızlı yanıt veren model seç
2	QualityPriority	En yetkin model seç
3	Manual	Belirli backend'e kilitle

Fallback Zinciri (Chain)

Ana Model (örn: gpt-4o via OpenRouter) → Timeout/Error? 
→ Yedek Model (örn: claude-haiku via Ollama-MacStudio) → Timeout/Error? 
→ Son Çare (örn: gemma via Ollama-local)

Internal LLM Controller — internal routing

#	Method	Route	Auth	Description
3	GET	/api/llm-gateway/internal/backends	InternalAPI Key	Backend listesi + sağlık durumu
4	POST	/api/llm-gateway/internal/route	InternalAPI Key	Manuel routing ({ model, strategy })

LLM Backend Config (via LLM Settings API)

#	Method	Route	Auth	Description
5	GET	/api/admin/llm/backends?page={int}&pageSize={int}	Required	Backend listesi (PaginatedList<LlmBackendDto>)
6	POST	/api/admin/llm/backends	Required	Yeni backend — 201 Created (CreateLlmBackendCommand: name, displayName, provider, defaultModel, availableModels: string[], baseUri, apiKey, priority, retryCount, timeoutSeconds)
7	PUT	/api/admin/llm/backends/{backendId:guid}	Required	Backend güncelle
8	DELETE	/api/admin/llm/backends/{backendId:guid}	Required	Backend sil

LlmBackendDto

{
  "id": "guid",
  "name": "ollama-local",
  "displayName": "Local Ollama",
  "provider": "Ollama",
  "baseUri": "http://host.docker.internal:11434",
  "defaultModel": "qwen3.5:cloud",
  "availableModels": ["embeddinggemma:latest", "gemma4:e4b", "qwen3.5:cloud"],
  "priority": 3,
  "retryCount": 2,
  "timeoutSeconds": 180,
  "isActive": true,
  "currentCost": 0.00,
  "totalTokensProcessed": 239524
}