convez.ai
MCP ServerBusca & PesquisaAvançado
FeanorsCodeSL

Thorondor

FeanorsCodeSL/thorondor

Busca semântica self-hosted e soberana para agentes IA

Ver no GitHub
BomPluginScore · de 0 a 100

Um servidor MCP self-hosted para busca semântica na web, projetado para agentes IA. Substitui APIs de busca hospedadas (Exa, Tavily) com um pipeline on-premises que descobre URLs via SearXNG, extrai conteúdo com Crawl4AI, realiza chunking semântico com BGE-M3 e reranqueia passagens antes de retornar citações verificadas.

Instalação

$npx convez-ai FeanorsCodeSL/thorondor

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
75%
Último commit
há 2 meses
Versão
v2026.8.8
Issues abertas
0
Contribuidores
2

Casos de uso

  • Agentes IA que precisam fazer pesquisa web com dados locais/privados
  • Organizações que exigem controle total sobre indexação e retenção de dados
  • Pipelines de busca customizados com reranking local

Veredito

Solução técnica robusta para quem precisa de busca web soberana em ambiente controlado. Requer expertise em Docker, embeddings e infra on-premises; não é plug-and-play, mas oferece controle total sem vendor lock-in.

README

A tradução para o português deste README ainda está na fila.

Thorondor

Public alpha: Thorondor is ready for local self-hosted evaluation, but it is not a managed production service. It does not include built-in endpoint authentication or rate limiting; expose it only behind your own proxy/security layer.

A self-hosted, data-sovereign semantic web-search service for agents — discovers URLs through SearXNG, crawls pages via Crawl4AI, chunks content with a first-party semantic chunker, reranks passages against the original query, and returns cited evidence through REST and MCP with no mandatory hosted vendor.

What It Is

Thorondor is a local semantic web-search stack designed to replace hosted search-for-agents APIs (Exa, Tavily, and equivalents) with an on-premises, operator-controlled pipeline. It uses SearXNG for multi-engine URL discovery, Crawl4AI for JavaScript-capable page crawling, a first-party ClusterSemanticChunker backed by BGE-M3 embeddings for globally-optimal chunk boundaries, and BGE-reranker-v2-m3 to score passages against the original query before assembly. The orchestrator exposes both POST /v1/search (REST) and an MCP web_search tool; both surfaces return the same versioned SearchResponse envelope with passages, citations, and stats. No persistent corpus, vector store, or implemented cache exists — all content is fetched live, processed, returned, and discarded.

Architecture Overview

query
  -> optional LLM query planner (subquery expansion)
  -> SearXNG multi-engine URL discovery
  -> URL safety pre-filter (SSRF/IP blocklist)
  -> domain allow/block policy + selection scoring
  -> Crawl4AI page extraction (concurrent, per-host bounded)
  -> trafilatura HTML-to-Markdown cleaning + content dedup
  -> semantic chunking service (ClusterSemanticChunker + BGE-M3 embeddings)
  -> lexical candidate prefilter (keeps top-50 before reranking)
  -> batched reranking (BGE-reranker-v2-m3)
  -> relevance floor filter
  -> token-budget assembly -> passages + citations
  -> SearchResponse (REST or MCP)

All inter-service traffic travels over an internal Compose network. Crawl4AI's outbound HTTP exits through the embedded SSRF egress proxy.

Repository Layout

PathTypeDescription
orchestrator/serviceFastAPI app: /v1/search, /search (compat), /healthz, MCP /mcp
semantic-chunking-service/serviceFastAPI chunker: /chunk, /healthz — ClusterSemanticChunker + OpenAI-compatible embedding client
ssrf-proxy/serviceMinimal async HTTP CONNECT proxy that blocks RFC-1918 and embedded-IPv4 IPv6 targets
searxng/configSearXNG settings.yml mounted read-only by Compose
models/artifactLocal GGUF model files consumed by the llama.cpp profile (not committed)
scripts/scriptsdeploy.ps1, deploy-llamacpp.ps1, smoke.ps1, check-release-guard.ps1 (PowerShell) + Bash equivalents
docker-compose.ymlconfigCore stack: orchestrator, chunker, SearXNG, Crawl4AI, egress-proxy; bundled-models profile adds TEI embedding + reranker
docker-compose.llamacpp.ymlconfigOverride: swaps embedding and reranker to local llama.cpp containers using GGUF files under models/
.env.exampleconfigTemplate for .env — every key the Python settings loader requires
.env.llamacpp.exampleconfigTemplate for .env.llamacpp — llama.cpp image SHA, GGUF paths, and batch sizes
docs/architecture/docsOperational architecture reference (overview, pipeline, deployment, deps, security, config)
docs/plans/docsActive remediation and implementation plans
.agents/skills/thorondor-web-search/skillRepo-local agent skill for calling the running service
LICENSElicenseMIT
THIRD-PARTY-NOTICES.mdlicenseThird-party runtime image and package notices

Prerequisites

  • Docker Desktop — installed, running, and configured for Linux containers.
  • GGUF model files (llama.cpp profile only) — bge-m3.gguf and bge-reranker-v2-m3.gguf placed under models/. Verify model license terms before downloading weights.
  • Hardware — tested on Windows 10/11 with Docker Desktop (WSL2 backend) and on ARM64 (NVIDIA DGX Spark). The llama.cpp image is pinned to a SHA known to work on both architectures. GPU acceleration is not required; CPU inference works but is slower.
  • PowerShell 7+ for the deploy and smoke scripts. Bash equivalents exist under scripts/.

Quickstart — Windows with llama.cpp (fully local)

# 1. Clone and enter the repo
git clone <repo-url> thorondor
Set-Location thorondor

# 2. Create environment files from examples
Copy-Item .env.example .env
Copy-Item .env.llamacpp.example .env.llamacpp

# 3. Create the models directory and place GGUF files
New-Item -ItemType Directory -Force models | Out-Null
# Copy bge-m3.gguf and bge-reranker-v2-m3.gguf into models\

# 4. Deploy: copies env files, generates SEARXNG_SECRET, validates Compose,
#    builds first-party images, starts all services, runs a smoke search
.\scripts\deploy-llamacpp.ps1

The script exits non-zero on any failure. After a successful deploy:

# Health check
Invoke-RestMethod http://localhost:8080/healthz

# Quick search
$body = @{ query = "latest Python packaging tools 2025"; token_budget = 3000 } | ConvertTo-Json
Invoke-RestMethod http://localhost:8080/v1/search -Method Post -ContentType "application/json" -Body $body

To run the investigation-mode smoke test (broader queries + URL diagnostics):

.\scripts\smoke.ps1 `
  -ComposeFiles @("docker-compose.yml","docker-compose.llamacpp.yml") `
  -EnvFiles @(".env",".env.llamacpp") `
  -Profile llamacpp-models `
  -Investigation

Quickstart — BYO Embedding and Reranker Endpoints

If you already operate OpenAI-compatible embedding and reranker servers (vLLM, TEI, Infinity, etc.), skip the llama.cpp profile entirely and point the core stack at your endpoints:

# 1. Copy base env only
Copy-Item .env.example .env

# 2. Edit .env — set your external endpoints
# EMBEDDING_ENDPOINT=http://your-embedding-host:8082
# EMBEDDING_MODEL=BAAI/bge-m3
# RERANKER_ENDPOINT=http://your-reranker-host:8081
# RERANKER_MODEL=BAAI/bge-reranker-v2-m3
# RERANKER_PATH=/rerank
# RERANKER_HEALTH_PATH=/health

# 3. Deploy without the llama.cpp override
.\scripts\deploy.ps1 -Profile ""

The bundled-models profile (TEI containers) is still available if you want to run embedding and reranker inside Docker without GGUF files:

.\scripts\deploy.ps1 -Profile bundled-models

REST API

POST /v1/search

POST http://localhost:8080/v1/search
Content-Type: application/json

{
  "query": "what changed in the EU AI Act timeline in 2025",
  "search_profile": "research",
  "token_budget": 4000,
  "max_urls": 8,
  "max_passages": 10,
  "freshness": "year",
  "domains": ["eur-lex.europa.eu", "europarl.europa.eu"],
  "exclude_domains": ["example.com"],
  "decompose": true,
  "include_raw_markdown": false
}

PowerShell example:

$body = @{
  query         = "what changed in the EU AI Act timeline in 2025"
  search_profile = "research"
  token_budget  = 4000
} | ConvertTo-Json

Invoke-RestMethod http://localhost:8080/v1/search `
  -Method Post `
  -ContentType "application/json" `
  -Body $body

curl example:

curl -s -X POST http://localhost:8080/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query":"EU AI Act 2025 timeline","search_profile":"research","token_budget":4000}' \
  | python -m json.tool

Request fields

FieldTypeDefaultDescription
querystring (required)—Information need, max 500 chars. Reranking always scores against this string, not sub-queries.
search_profile"quick" | "research" | "deep"nullSelects a preset bundle of token_budget, max_urls, max_passages defaults.
token_budgetint 1–16000profile or server defaultControls passage assembly, not crawl cost.
max_urlsint 1–20profile or server defaultCap on URLs selected before crawling.
max_passagesint 1–50profile defaultHard cap on returned passages after token budgeting.
decomposebooltrueWhether the optional LLM planner may expand the query into sub-queries. No-op when LLM_ENDPOINT is blank.
freshness"day" | "week" | "month" | "year"nullDiscovery time-range hint passed to SearXNG.
domainslist[str]nullPer-call domain allowlist. Combined with ALLOWLIST_ONLY if set.
exclude_domainslist[str]nullPer-call domain blocklist merged with DOMAIN_BLOCKLIST.
include_raw_markdownboolfalseAttach raw crawled markdown for cited pages in raw_markdown[].

Response envelope (SearchResponse)

{
  "query": "...",
  "schema_version": "thorondor.search.v1",
  "passages": [
    {
      "text": "...",
      "score": 0.87,
      "token_count": 134,
      "citation_id": 1,
      "provenance": "external_web",
      "trust": "untrusted"
    }
  ],
  "citations": [
    { "id": 1, "url": "https://...", "title": "..." }
  ],
  "stats": {
    "sub_queries": ["..."],
    "urls_discovered": 18,
    "urls_selected": 6,
    "urls_crawled_ok": 5,
    "urls_crawled_failed": 1,
    "chunks_produced": 43,
    "chunks_sent_to_reranker": 43,
    "reranked": true,
    "tokens_returned": 3812,
    "elapsed_ms": 4200,
    "reason": null
  },
  "raw_markdown": null
}

Key stats fields:

FieldMeaning
rerankedfalse when the reranker was unreachable; passages are still returned sorted by position.
reasonNon-null closed enum when the search ended before normal assembly: no_results_from_discovery, no_urls_after_selection, all_crawls_failed, no_chunks_after_dedup, no_chunks_after_rerank.
embedding_degradedtrue when the chunker fell back to token-based splitting because embeddings failed.
url_diagnosticsPer-URL selection decisions (populated when include_raw_markdown is true or the investigation smoke test is used).

An empty-passage response with stats.reason set is a normal 200, not an error. The caller should read reason rather than interpreting passages.length == 0 alone.

POST /search is a backwards-compatible alias for POST /v1/search.

MCP

Mount the MCP endpoint in your agent's configuration:

http://localhost:8080/mcp

Transport: streamable HTTP (stateless_http=True). The server ID is thorondor.

The single exposed tool is web_search. Its parameters mirror the REST request exactly. Returns the same SearchResponse dict shape as the REST endpoint, serialised by model_dump().

Example MCP tool call (Claude SDK style):

{
  "name": "web_search",
  "input": {
    "query": "EU AI Act enforcement 2025",
    "search_profile": "research",
    "token_budget": 4000
  }
}

The MCP server also supports stdio transport via python -m orchestrator.mcp_server for environments that require it.

Health and Observability

/healthz

{
  "status": "ok",
  "dependencies": {
    "searxng": true,
    "crawl4ai": true,
    "chunker": true,
    "embedding": true,
    "reranker": true
  },
  "hard_failures": [],
  "degraded_dependencies": []
}

status is "degraded" if any dependency probe fails. hard_failures lists searxng or chunker — either alone causes SearchDependencyUnavailable (503). degraded_dependencies lists crawl4ai, embedding, and reranker; the pipeline tolerates their absence with reduced quality.

X-Request-ID

Every REST and MCP request generates or accepts X-Request-ID. The same ID is returned to the caller and forwarded to all downstream seams (SearXNG, Crawl4AI, chunker, embedding, reranker, LLM planner).

Structured logging

One JSON log line is emitted per completed search:

{
  "level": "INFO",
  "logger": "orchestrator.pipeline",
  "message": "search_completed",
  "request_id": "a3f7...",
  "event": "search_completed",
  "query_hash": "4a8b1c2d",
  "sub_query_count": 2,
  "urls_discovered": 18,
  "urls_selected": 6,
  "urls_crawled_ok": 5,
  "urls_crawled_failed": 1,
  "reranked": true,
  "reason": null,
  "elapsed_ms": 4200
}

Logs never contain raw query text, page markdown, secret values, userinfo components, or URL query strings.

Configuration Reference

All keys must be present in .env (leave optional keys blank rather than deleting them). The Python settings loader raises RuntimeError on startup for any missing key.

Service URLs

VariableDefaultDescription
SEARXNG_URLhttp://searxng:8080Internal SearXNG base URL used by the orchestrator.
CRAWL4AI_URLhttp://crawl4ai:11235Internal Crawl4AI API base URL.
CHUNKER_URLhttp://chunker:8000Internal semantic chunking service base URL.
SEARXNG_BASE_URLhttp://searxng:8080/External base URL passed to SearXNG for self-referencing links (Compose env).
ORCHESTRATOR_HOST127.0.0.1Host interface bound by Compose. Keep localhost for personal use; set 0.0.0.0 only behind firewall/auth.
ORCHESTRATOR_PORT8080Host port bound to the orchestrator container (Compose env).

Logging

VariableDefaultDescription
LOG_LEVELINFOOrchestrator log level.
CHUNKER_LOG_LEVELINFOChunker service log level.
PROXY_LOG_LEVELINFOSSRF egress proxy log level.

Healthcheck

VariableDefaultDescription
HEALTHCHECK_TIMEOUT_S2.0Per-dependency probe timeout in seconds.
HEALTHCHECK_MAX_CONNECTIONS8Max connections in the healthcheck HTTP client pool.
HEALTHCHECK_MAX_KEEPALIVE_CONNECTIONS4Max keepalive connections in the healthcheck client pool.

Search Profiles

VariableDefaultDescription
MAX_SUBQUERIES3Maximum sub-queries the planner may produce.
DEFAULT_TOKEN_BUDGET4000Token budget used when no profile and no explicit token_budget is given.
SEARCH_PROFILE_QUICK_TOKEN_BUDGET2000Token budget for the quick profile.
SEARCH_PROFILE_QUICK_MAX_URLS5Max URLs for quick.
SEARCH_PROFILE_QUICK_MAX_PASSAGES5Max passages for quick.
SEARCH_PROFILE_RESEARCH_TOKEN_BUDGET8000Token budget for research.
SEARCH_PROFILE_RESEARCH_MAX_URLS12Max URLs for research.
SEARCH_PROFILE_RESEARCH_MAX_PASSAGES20Max passages for research.
SEARCH_PROFILE_DEEP_TOKEN_BUDGET16000Token budget for deep.
SEARCH_PROFILE_DEEP_MAX_URLS20Max URLs for deep.
SEARCH_PROFILE_DEEP_MAX_PASSAGES40Max passages for deep.

Crawl Tuning

VariableDefaultDescription
MAX_URLS6Default max URLs when no profile and no explicit max_urls is given.
CRAWL_CONCURRENCY4Total concurrent Crawl4AI requests (1–20).
CRAWL_PER_HOST_CONCURRENCY1Concurrent requests per hostname.
CRAWL_TIMEOUT_S15Per-URL crawl timeout in seconds.
CRAWL_RESPECT_ROBOTS_TXTtrueWhether Crawl4AI observes robots.txt.
CRAWL_VALIDATE_REDIRECTStruePreflight-check redirect chains for SSRF targets before sending to Crawl4AI.
CRAWL_MAX_PREFLIGHT_REDIRECTS5Max redirect hops to follow during preflight validation.

Markdown Extraction

VariableDefaultDescription
MARKDOWN_EXTRACTORtrafilaturaMust be trafilatura (only supported value).
MARKDOWN_EXTRACTOR_FAVOR_RECALLtrueTrafilatura include_tables-style recall mode.
MARKDOWN_EXTRACTOR_INCLUDE_COMMENTSfalseInclude comment sections in extracted text.
MARKDOWN_EXTRACTOR_INCLUDE_TABLEStrueInclude HTML table content.
MARKDOWN_EXTRACTOR_DEDUPLICATEtrueEnable trafilatura's internal deduplication.

Chunker Tuning

VariableDefaultDescription
CHUNKER_DEFAULT_STRATEGY_VERSIONcluster-semantic@1Default chunking strategy version sent to the chunker service.
CHUNKER_MAX_SEGMENTS_DP10000Segment count above which the chunker falls back from DP to greedy-semantic (OOM guard).
REWARD_CACHE_MAX_SIZE100000LRU cache bound for the DP reward function.
CHUNKER_MEM_LIMIT768mDocker memory limit for the chunker container (Compose env).

Embedding (used by the chunker service)

VariableDefaultDescription
EMBEDDING_ENDPOINThttp://embedding:80OpenAI-compatible /v1/embeddings server base URL.
EMBEDDING_MODELBAAI/bge-m3Model name sent in embedding requests.
EMBEDDING_API_KEY(blank)Optional bearer token for the embedding server.
EMBEDDING_BATCH_SIZE64Texts per embedding API call.
EMBEDDING_TIMEOUT_S60Embedding request timeout in seconds.

Reranker

VariableDefaultDescription
RERANKER_ENDPOINThttp://reranker:80Reranker server base URL.
RERANKER_MODELBAAI/bge-reranker-v2-m3Model name sent in rerank requests.
RERANKER_PATH/rerankRerank endpoint path.
RERANKER_HEALTH_PATH/healthReranker health endpoint path.
RERANKER_API_KEY(blank)Optional bearer token for the reranker.
RERANKER_BATCH_SIZE32Chunks per reranker API call.
RERANKER_TIMEOUT_S30Reranker request timeout in seconds.
RELEVANCE_SCORE_FLOOR0.0Passages with reranker score ≤ this value are dropped after reranking (0.0 disables the filter).

Optional LLM Planner

VariableDefaultDescription
LLM_ENDPOINT(blank)Optional OpenAI-compatible chat completions server for query decomposition. Leave blank to use IdentityPlanner (no decomposition).
LLM_MODEL(blank)Model name sent to the LLM planner. Required when LLM_ENDPOINT is set.
LLM_API_KEY(blank)Optional bearer token for the LLM planner.

URL Safety and SSRF Protection

VariableDefaultDescription
URL_SAFETY_BLOCKED_IP_CATEGORIESloopback,link_local,private,reserved,multicast,unspecifiedIP address categories blocked before crawl.
URL_SAFETY_BLOCKED_SPECIAL_IPS169.254.169.254,fd00:ec2::254Specific IPs blocked regardless of category (AWS/cloud metadata endpoints).
URL_SAFETY_NAT64_NETWORKS64:ff9b::/96IPv6 NAT64 networks; embedded IPv4 is extracted and re-checked.
URL_SAFETY_SIX_TO_FOUR_NETWORKS2002::/16IPv6 6-to-4 networks; embedded IPv4 is extracted and re-checked.
URL_SAFETY_IPV4_COMPAT_NETWORKS::/96IPv4-compatible IPv6 networks; embedded IPv4 is extracted and re-checked.

Domain Allow/Block Lists

VariableDefaultDescription
DOMAIN_BLOCKLIST(blank)Comma-separated domains excluded from all searches. Supports subdomain matching.
DOMAIN_ALLOWLIST(blank)Comma-separated domains permitted when ALLOWLIST_ONLY=true.
ALLOWLIST_ONLYfalseWhen true, restricts all crawls to DOMAIN_ALLOWLIST + per-call domains.

SSRF Egress Proxy

VariableDefaultDescription
PROXY_HOST0.0.0.0Proxy listen address.
PROXY_PORT8888Proxy listen port.
PROXY_MAX_HEADER_BYTES65536Max bytes read for HTTP request headers.
PROXY_READ_CHUNK_BYTES4096Read chunk size for incoming data.
PROXY_RELAY_CHUNK_BYTES65536Relay chunk size for proxied data.
PROXY_BLOCKED_IP_CATEGORIES(same as URL_SAFETY)IP categories blocked by the proxy itself.
PROXY_BLOCKED_SPECIAL_IPS(same as URL_SAFETY)Special IPs blocked by the proxy.
PROXY_NAT64_NETWORKS64:ff9b::/96NAT64 networks for the proxy's IP expansion.
PROXY_SIX_TO_FOUR_NETWORKS2002::/166-to-4 networks for the proxy's IP expansion.
PROXY_IPV4_COMPAT_NETWORKS::/96IPv4-compat networks for the proxy's IP expansion.

Crawl4AI Proxy Pass-Through

VariableDefaultDescription
CRAWL4AI_HTTP_PROXYhttp://egress-proxy:8888HTTP proxy for Crawl4AI outbound connections.
CRAWL4AI_HTTPS_PROXYhttp://egress-proxy:8888HTTPS proxy for Crawl4AI outbound connections.
CRAWL4AI_ALL_PROXYhttp://egress-proxy:8888All-protocol proxy fallback.
CRAWL4AI_NO_PROXY(blank)Comma-separated hosts to bypass the proxy.

API Keys

VariableDefaultDescription
SEARXNG_SECRET(blank — generated by deploy script)SearXNG instance secret. Generated by deploy.ps1; never commit a real value.
SEARXNG_API_KEY(blank)Optional bearer token accepted by SearXNG for its JSON API.
CRAWL4AI_API_KEY(blank)Optional bearer token for the Crawl4AI API.
CHUNKER_API_KEY(blank)Optional bearer token for the chunking service.
RERANKER_API_KEY(blank)Optional bearer token for the reranker.
EMBEDDING_API_KEY(blank)Optional bearer token for the embedding server (read by chunker).
LLM_API_KEY(blank)Optional bearer token for the LLM planner.

llama.cpp Overrides (.env.llamacpp)

VariableDefaultDescription
LLAMACPP_IMAGEghcr.io/ggml-org/llama.cpp:server@sha256:4c52f549...Pinned llama.cpp server image SHA.
LLAMACPP_EMBEDDING_MODEL/models/bge-m3.ggufContainer path to the embedding GGUF (mounted from ./models).
LLAMACPP_EMBEDDING_ALIASbge-m3Model alias used in embedding API requests.
LLAMACPP_EMBEDDING_POOLINGclsPooling strategy for the embedding model.
LLAMACPP_EMBEDDING_CONTEXT8192Context length for the embedding server.
LLAMACPP_RERANKER_MODEL/models/bge-reranker-v2-m3.ggufContainer path to the reranker GGUF.
LLAMACPP_RERANKER_ALIASbge-reranker-v2-m3Model alias used in reranker API requests.
LLAMACPP_RERANKER_CONTEXT8192Context length for the reranker server.
LLAMACPP_BATCH8192Batch size for llama.cpp.
LLAMACPP_UBATCH8192Micro-batch size for llama.cpp.

Development Checks

# Create or activate a Python environment, then install test dependencies
python -m pip install `
  -r orchestrator\requirements.txt `
  -r orchestrator\requirements-dev.txt `
  -r semantic-chunking-service\requirements.txt `
  -r semantic-chunking-service\requirements-dev.txt

# Run all tests
python -m pytest semantic-chunking-service\tests orchestrator\tests -v

# Run local SonarQube analysis
# Requires SONAR_HOST_URL and SONAR_TOKEN in the environment.
.\scripts\sonar.ps1

# Validate base Compose config
docker compose --env-file .env -f docker-compose.yml config

# Validate llama.cpp overlay config
docker compose --env-file .env --env-file .env.llamacpp `
  -f docker-compose.yml -f docker-compose.llamacpp.yml `
  --profile llamacpp-models config

# Check release guard (CI parity check)
.\scripts\check-release-guard.ps1

Troubleshooting

Docker pipe error (dockerDesktopLinuxEngine not found) Start Docker Desktop and wait until its system tray icon reports "running". Then re-run the deploy script.

Missing GGUF files deploy-llamacpp.ps1 validates model paths before starting Compose. Either place the files under models\ matching the paths in .env.llamacpp, or edit .env.llamacpp to point to your actual filenames.

embedding=false in /healthz The chunker is running but cannot reach the embedding server. Check EMBEDDING_ENDPOINT in .env and verify the embedding container is healthy: docker compose logs embedding.

reranker=false in /healthz The reranker server is unreachable. For llama.cpp, verify the GGUF file loads without error: docker compose --env-file .env --env-file .env.llamacpp -f docker-compose.yml -f docker-compose.llamacpp.yml logs reranker. For remote endpoints, check RERANKER_ENDPOINT and RERANKER_HEALTH_PATH.

stats.reranked=false in search response The reranker was unreachable at query time. Passages are returned sorted by position (no semantic ranking). The service continues to function; fix the reranker and passages will be reranked again.

Port conflict on 8080 Change ORCHESTRATOR_PORT in .env to an available port, then restart: docker compose up -d orchestrator.

Expose beyond localhost Compose binds the orchestrator to 127.0.0.1 by default. To expose it to another host, set ORCHESTRATOR_HOST=0.0.0.0 and put the service behind TLS, authentication, and rate limiting first. Thorondor does not implement endpoint authentication itself.

SEARXNG_SECRET not set error Run .\scripts\deploy.ps1 (or deploy-llamacpp.ps1) rather than docker compose up directly — the deploy script generates the secret when the field is blank.

All crawls failing (urls_crawled_ok=0) Check Crawl4AI logs: docker compose logs crawl4ai. Common causes: slow network, robots.txt refusals (CRAWL_RESPECT_ROBOTS_TXT=true), or proxy misconfiguration. Increase CRAWL_TIMEOUT_S for slow sites.

No results from SearXNG SearXNG may be rate-limited or blocking engines may be unavailable. Check docker compose logs searxng. The SearXNG web UI is not published by the default Compose stack; inspect it from inside the Compose network or add a temporary local-only port mapping during debugging.

License

MIT — see LICENSE. Third-party notices: THIRD-PARTY-NOTICES.md.

Ver o original no GitHub

Bom para

Relacionados