docs(llm): correct the 15.8 LLM overview against the implementation - #473
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Reviewed
15.8/config/llm-overview.rstagainst 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 thefess-llm-ollama,fess-llm-openaiandfess-llm-geminiplugins.Corrections
availability.check.intervalgetConfigInt(), which accepts only values> 0, so0falls back to the default60. The check cannot be disabled through this property.app/WEB-INF/classes/fess_llm+<componentName>.xml, with the provider-to-component-name table.rag.llm.nameollama, 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 documentsnone.fess_config.propertiespathapp/WEB-INF/conf/app/WEB-INF/classes/(and/etc/fess/for package installs), consistent with the rest of the docs.thinking.budget,top.pandreasoning.effortreasoning.effortis OpenAI only,top.pis not available for Gemini, andthinking.budgetis ignored by OpenAI. Also notes that thedefault.*fallback tier is Ollama only.search-phase fallback, not a phase, and the non-streamingPOST /api/v2/chatruns no evaluation phase.gpt-5-minidefault.Two
.. warning::blocks were added to the system prompt section: a redefinition file replaces the whole component definition (omitted properties revert to unset), and copyingfess_llm++.xmlitself intoapp/WEB-INF/classes/registers the component twice and prevents startup withTooManyRegistrationComponentException.Additions
rag.chat.enableddefault value (false).directprompt type is not invoked in the current version.Verification
fess_llm++.xml, while a secondfess_llm++.xmlon the classpath fails withTooManyRegistrationComponentException.:doc:targets each. The only literal differences between languages are two placeholders that are prose rather than identifiers (fess_llm+{component name}.xmlandrag.llm.ollama.default.{parameter}).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.rstdocuments copyingfess_llm++.xmlintoapp/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.rstandrag-chat.rstall still use theapp/WEB-INF/conf/fess_config.propertiespath.