Skip to content

docs(llm): correct the 15.8 LLM overview against the implementation - #473

Merged
marevol merged 1 commit into
masterfrom
docs-15.8-llm-overview-accuracy
Aug 9, 2026
Merged

docs(llm): correct the 15.8 LLM overview against the implementation#473
marevol merged 1 commit into
masterfrom
docs-15.8-llm-overview-accuracy

Conversation

@marevol

@marevol marevol commented Aug 8, 2026

Copy link
Copy Markdown
Contributor

Summary

Reviewed 15.8/config/llm-overview.rst against the implementation and corrected it, then propagated the result to all seven languages (ja, en, de, es, fr, ko, zh-cn).

Sources of truth: fess (master) AbstractLlmClient / LlmClientManager / ChatClient / ChatPhaseCallback / fess_config.properties, and the fess-llm-ollama, fess-llm-openai and fess-llm-gemini plugins.

Corrections

Topic Was Now
availability.check.interval "0 disables it" The value is read via getConfigInt(), which accepts only values > 0, so 0 falls back to the default 60. The check cannot be disabled through this property.
System prompt customization "You must edit the DI XML inside the JAR" Documents the supported LastaDi component redefinition file app/WEB-INF/classes/fess_llm+<componentName>.xml, with the provider-to-component-name table.
rag.llm.name "Only the Ollama client is enabled by default" The default is ollama, and the value selects the DI component name {rag.llm.name}LlmClient. Leaving the default while installing only a non-Ollama plugin enables no client at all and logs [LLM] LlmClient not found. componentName=ollamaLlmClient. Also documents none.
fess_config.properties path app/WEB-INF/conf/ app/WEB-INF/classes/ (and /etc/fess/ for package installs), consistent with the rest of the docs.
Provider-specific parameters Implied all providers support thinking.budget, top.p and reasoning.effort Per-provider support matrix. reasoning.effort is OpenAI only, top.p is not available for Gemini, and thinking.budget is ignored by OpenAI. Also notes that the default.* fallback tier is Ollama only.
Architecture One unconditional eight-step flow Scoped to the streaming search intent. Query regeneration is a search-phase fallback, not a phase, and the non-streaming POST /api/v2/chat runs no evaluation phase.
OpenAI description GPT-4 GPT-5, matching the gpt-5-mini default.

Two .. warning:: blocks were added to the system prompt section: a redefinition file replaces the whole component definition (omitted properties revert to unset), and copying fess_llm++.xml itself into app/WEB-INF/classes/ registers the component twice and prevents startup with TooManyRegistrationComponentException.

Additions

  • rag.chat.enabled default value (false).
  • Plugin installation through the admin UI, in addition to manual JAR placement.
  • A note that the direct prompt type is not invoked in the current version.
  • Links to the chat search guide and the chat API reference.

Verification

  • The system prompt override behaviour was confirmed empirically against lasta-di 2.0.0, not only by reading the source: a redefinition file overrides a component declared in a plugin's fess_llm++.xml, while a second fess_llm++.xml on the classpath fails with TooManyRegistrationComponentException.
  • All seven files build without warnings under Sphinx.
  • All seven files are structurally identical: 44 table rows, 114 literal tokens and 12 :doc: targets each. The only literal differences between languages are two placeholders that are prose rather than identifiers (fess_llm+{component name}.xml and rag.llm.ollama.default.{parameter}).
  • Values confirmed unchanged because they are already correct: the three default models and endpoints, the authentication headers, rag.chat.* defaults, max.concurrent.requests (5), concurrency.wait.timeout (30000, and the resulting error really is a rate-limit error), chat.evaluation.max.relevant.docs (3), the ten prompt type names, and the five phase names.

Three Korean section underlines that were shorter than their East Asian display width are also fixed; they produced Sphinx warnings and predate this change.

Follow-ups (not in this PR)

  • rag-chat.rst documents copying fess_llm++.xml into app/WEB-INF/, which is the procedure that breaks startup, and describes the concurrency wait timeout as a timeout error when the code raises a rate-limit error.
  • llm-ollama.rst, llm-openai.rst, llm-gemini.rst and rag-chat.rst all still use the app/WEB-INF/conf/fess_config.properties path.
  • The 15.7 copies of this page carry the same claims, but should be checked against the 15.7 branch rather than master.

Verified ja/15.8/config/llm-overview.rst against fess (master) and the
fess-llm-ollama / fess-llm-openai / fess-llm-gemini plugins, then propagated
the result to all seven languages.

Corrections:
- availability.check.interval: drop the false "0 disables it" claim. The
  value is read through getConfigInt(), which only accepts values greater
  than zero, so 0 falls back to the default 60 and the periodic check cannot
  be disabled through this property.
- System prompts: replace "you must edit the DI XML inside the JAR" with the
  supported LastaDi component redefinition mechanism
  (app/WEB-INF/classes/fess_llm+<componentName>.xml), and warn that copying
  fess_llm++.xml itself registers the component twice and prevents startup
  with TooManyRegistrationComponentException.
- rag.llm.name: state the default (ollama) and explain that the value selects
  a DI component name, so leaving the default while installing only a
  non-Ollama plugin enables no LLM client at all. Document the none value.
- fess_config.properties location: app/WEB-INF/conf/ became
  app/WEB-INF/classes/ (and /etc/fess/ for package installs), matching the
  rest of the documentation.
- Provider-specific parameters: replace the note implying that every provider
  supports thinking.budget, top.p and reasoning.effort with a per-provider
  support matrix, and note that the default.* fallback tier is Ollama only.
- Architecture: scope the eight-step flow to the streaming search intent, note
  that query regeneration is a search-phase fallback rather than a phase, and
  that the non-streaming POST /api/v2/chat runs no evaluation phase.
- OpenAI description: GPT-4 became GPT-5, matching the gpt-5-mini default.

Additions:
- rag.chat.enabled default value (false).
- Plugin installation through the admin UI.
- Note that the direct prompt type is not invoked in the current version.
- Links to the chat search guide and the chat API reference.

Also fix three Korean section underlines that were shorter than their East
Asian display width and produced Sphinx warnings.
@marevol
marevol merged commit 55bc455 into master Aug 9, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant