Optional AI providers

You can write pages, organize sources, search, review changes, and use Ask’s evidence pack without an AI provider. Optional providers add specific abilities; they do not automatically write a wiki or make every answer correct.

External service availability and charges are separate from dtxWiki. Review the provider's current service terms and API pricing before enabling it.

The solid path is the default evidence-based response. The dashed path is an operator's separate choice to use a model. Both paths require you to read the evidence; a generated answer does not make its sources correct.

What the choices do

Choice	What changes	Default
Ask LLM provider	Composes a prose answer from the question and retrieved evidence	Off (none)
Embedding provider	Adds a vector-based meaning-search lane alongside existing search	Off (none)
Reranking provider	Reorders retrieved candidates through an external ranking service	Off (none)
External AI app via MCP	Lets that app request permitted tools from dtxWiki	No connection until you configure one

An LLM generates language. An embedding converts text into numbers so related text can be compared. A reranker reorders candidate search results. These are distinct configurations; connecting Claude Code or another MCP client does not configure them.

Without an LLM provider, Ask returns a deterministic retrieval summary and evidence. With a provider, its composer is instructed to answer only from that evidence and cite it. Read the citations yourself; a generated answer can still be incomplete or wrong.

For ordinary users

Ask your server operator whether these services are enabled and where they run. A local model endpoint and a cloud API have different data destinations. Avoid sending confidential material to a provider unless your organization allows it.

If Ask shows an evidence summary rather than a composed answer, the provider may be off or unavailable. The fallback preserves access to the evidence. Warning codes llm_provider_unavailable and llm_composer_failed indicate a configuration or composition failure; send the warning text to the operator without sending credentials.

For your own AI client, use Connect an AI app. For ordinary search and Ask, use Search and Ask.

Enable an Ask provider: operator steps

The snapshot supports these LLM choices:

DTXWIKI_LLM_PROVIDER	Required secret
none	None
openai	DTXWIKI_OPENAI_API_KEY
anthropic	DTXWIKI_ANTHROPIC_API_KEY

1. Review your provider’s data handling and API billing, and obtain an approved API key. A chat-app subscription should not be assumed to supply an API credential.
2. Store the key in the protected runtime configuration or approved secrets mechanism. For systemd, the standard configuration is /etc/dtxwiki/dtxwiki.env. Keep the key out of shell history, public examples, and screenshots.
3. Set the provider selector, then restart the app and worker so they read the same environment. For systemd, a non-secret selector can be changed with sudo dtxwiki config set DTXWIKI_LLM_PROVIDER=openai, followed by sudo systemctl restart dtxwiki dtxwiki-worker.
4. Ask a simple question about a known published test page. Confirm the answer cites the right evidence and no provider warning appears.

The app sends the question and retrieved evidence to the provider. It does not need to send the entire workspace to compose this answer. Follow Privacy and safe sharing when choosing permitted content.

For a local installation, apply the same environment to the app and separate worker terminals before starting them. For Docker, provide the settings to the relevant service environments via a reviewed Compose configuration/override. Adding a variable only to the host shell or .env does not pass it through unless Compose references it.

Configure meaning search: operator steps

The actual provider registry accepts none, deterministic, and openai_compatible. deterministic is a hashing implementation for offline pipeline checks, not a learned semantic model.

For an existing OpenAI-compatible embedding endpoint, configure:

Setting	Purpose
DTXWIKI_EMBEDDING_PROVIDER=openai_compatible	Choose the endpoint adapter
DTXWIKI_EMBEDDING_BASE_URL	Endpoint base URL, commonly its /v1 address
DTXWIKI_EMBEDDING_MODEL	Model served by that endpoint
DTXWIKI_EMBEDDING_DIM	Vector size returned by that model
DTXWIKI_EMBEDDING_API_KEY	API key if the endpoint requires authentication

dtxWiki connects to a model server; it does not install, download, or operate that model server for you. Make sure the endpoint is reachable from the application and worker, not just from your laptop. A local endpoint can keep this processing on infrastructure you operate.

After configuring the protected environment, check it before rebuilding indexes:

# systemd installation: wrapper loads the production configuration
sudo dtxwiki embedding doctor

The probe checks the model endpoint, vector size, and latency using a short test phrase. Resolve errors first. When the model or dimension changes, schedule and run:

sudo dtxwiki reindex

The command rebuilds indexes using the current settings. It can process all accessible workspace content and make calls to the configured embedding service, so plan its time and API cost. For local use omit sudo and use the same environment; for Docker run the CLI inside the configured app service.

The optional reranking registry accepts none or api with DTXWIKI_RERANK_BASE_URL, DTXWIKI_RERANK_MODEL, and DTXWIKI_RERANK_API_KEY when required. It uses an external service; keep it off until the base search and embedding path work as expected.

If the provider fails

Ask falls back to its evidence pack when it cannot build or use the configured composer. Search can retain keyword and navigational results when optional semantic providers are unavailable. Do not interpret the fallback as a successful provider call: review warnings and run the appropriate diagnostics.

Do not solve dimension mismatch by guessing a number. Use the model endpoint’s returned dimension, update the configuration consistently, and rebuild the index. Check Troubleshooting for server and worker issues.

---

Version evidence: actual provider registry, Ask evidence and fallback behavior, embedding diagnostics, reindex command.