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.

Ask is an experimental menu that each person turns on in Settings → Labs with Show Ask menu; see Turn on Ask. The provider settings on this page neither show nor hide that menu.

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 dtxWiki so it reads the new environment. A local dtxwiki restarts its background worker together with the app. 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. In the browser you use for the check, open Settings, select Labs under Your account, and select Show Ask menu. Ask then appears under Knowledge. Use an Editor or Owner account; only those roles can send questions.
5. 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, set the variables in the terminal that starts dtxwiki, then start it. Its background worker receives the same settings, so no separate worker terminal is needed. 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.

With the default Ask retrieval mode in Settings → Workspace, Ask combines keyword and meaning search when embeddings are configured, and uses keyword search otherwise. A workspace Owner can fix the mode there; if the server cannot serve the chosen mode, Ask falls back to another one and shows a notice.

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.

Check the reranking connection

After configuring a rerank endpoint, use the wrapper that loads the production environment:

sudo dtxwiki rerank doctor

For a local installation, use the same environment without sudo. This probes reachability, ordering and latency with a small fixed example; it does not run the model service or verify factual accuracy. With provider none, it reports that no reranker is configured without calling an endpoint.

CLI source.

---

Version evidence: actual provider registry, Ask evidence and fallback behavior, embedding diagnostics, reindex command, Ask menu in Labs, background worker started by the app.