kongdeqiang
2026-10-12 7c687dd3c8fba9f7632f5e29d94a708e5f497abd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
package com.custom.webui.config.props;
 
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
 
/**
 * LLM 配置,前缀 {@code webui.llm}。
 *
 * <p>{@link #provider} 决定使用哪个 {@code LlmService} 实现:
 * <ul>
 *   <li>{@code ollama} —— 调用本地 Ollama(默认,生产使用)</li>
 *   <li>{@code mock} —— 本地模拟流式输出,未装 Ollama 时用于打通 SSE 链路</li>
 * </ul>
 */
@Data
@ConfigurationProperties(prefix = "webui.llm")
public class LlmProperties {
 
    private String provider = "openai-compat";
 
    private Ollama ollama = new Ollama();
 
    /**
     * OpenAI 兼容接口配置。
     *
     * <p>绝大多数推理服务都实现了 OpenAI 的 {@code /v1/chat/completions} 协议,
     * 因此这一份配置可以同时覆盖:vLLM、LM Studio、SGLang、Xinference、
     * one-api / new-api 网关,以及 OpenAI / DeepSeek / Kimi / 通义 / GLM 等云端 API。
     * 换服务只需要改 {@link OpenAiCompat#baseUrl} 与 {@link OpenAiCompat#model}。
     */
    private OpenAiCompat openaiCompat = new OpenAiCompat();
 
    private Defaults defaults = new Defaults();
 
    /**
     * 携带进 prompt 的历史消息条数上限。
     *
     * <p>这是**条数**上限,不是真正的约束 —— 真正会截断上下文的是
     * {@code num_ctx} 的 token 预算(见 {@link #contextCharBudget})。
     * 两者都要满足,取更严格的那个。
     */
    private int historyLimit = 20;
 
    /**
     * 整个 prompt(system + 历史 + 本轮输入)的字符预算。
     *
     * <p><b>为什么必须有这个预算</b>:Ollama 的 {@code num_ctx} 是硬上限,
     * 超出时它会**从开头截断**,而 system 消息(承载 RAG 资料与图片 OCR 文字)
     * 恰恰在最前面 —— 表现就是「模型完全不知道我给了图片/知识库内容」,
     * 而且不报任何错,极难排查。
     *
     * <p>默认按 {@code num_ctx=8192} 反推:中文场景 1 字符≈1 token,
     * 预留约一半给模型输出(长回答可能几千 token),
     * 再留一点余量给对话模板的额外开销,故取 4000 字符。
     * 如果你把 num_ctx 调大(如 32768),这个值也应同步放大。
     */
    private int contextCharBudget = 4000;
 
    /**
     * 单个部分(图片 OCR 文字 / RAG 资料)各自的字符上限。
     *
     * <p>比总预算小,是为了防止某一部分独占全部预算:
     * 一张整页截图的 OCR 文字可能有几千字,若不加限制,
     * 它会挤掉历史对话甚至用户本轮的问题。
     */
    private int perPartCharLimit = 2000;
 
    @Data
    public static class Ollama {
        private String baseUrl = "http://localhost:11434";
        private String defaultModel = "qwen2.5:7b";
        /** 流式请求超时,需给足时间,默认 5 分钟 */
        private int timeoutMillis = 300000;
        /** 是否把 reasoning 模型的 thinking 字段也推给前端 */
        private boolean includeThinking = false;
    }
 
    /**
     * OpenAI 兼容接口的配置段。
     *
     * <p>用 {@code openai-compat} 作为 provider 名而不是 {@code openai},
     * 是因为它同样用于本地 vLLM 等自建服务 —— 名字要反映「协议兼容」,
     * 而不是「调用 OpenAI 官方」。
     */
    @Data
    public static class OpenAiCompat {
        /** 基础地址,需含 /v1(如 http://127.0.0.1:10020/v1) */
        private String baseUrl = "http://127.0.0.1:10020/v1";
 
        /** API Key。本地服务一般不需要,留空即可 */
        private String apiKey = "";
 
        /** 默认模型名 */
        private String model = "qwen35";
 
        /** 流式请求超时(毫秒),思考型模型可能较慢 */
        private int timeoutMillis = 600000;
 
        /**
         * 单次生成的**输出** token 上限。
         *
         * <p>必须设置:思考型模型(Qwen3、DeepSeek-R1 等)会先生成大量推理内容,
         * 实测「让它只回复两个字」却生成了 256 个 token、耗时 8 秒,
         * 而最终正文只有 17 字。加上限制后同一请求降到 0.76 秒。
         *
         * <p>注意:这是**输出**上限,与 Ollama 的 {@code num_ctx}(输入+输出总窗口)
         * 不是一个概念,因此单独配置而不是复用。
         */
        private Integer maxTokens = 2048;
 
        /** 是否把推理内容(reasoning_content / think 标签)也推给前端展示 */
        private boolean includeThinking = false;
 
        /**
         * 是否尝试过滤「模型把推理写进正文」的泄漏。
         *
         * <p>默认关闭 —— 这是**启发式**规则,可能误伤正常内容。
         *
         * <p>什么时候需要打开:部分思考型模型(实测 Qwen3.5-397B-A17B 这类
         * MoE 推理模型)**并不总是**把推理放在 {@code reasoning_content} 字段,
         * 有时会把推理过程直接写进 {@code content} 正文(同一个请求重跑两次,
         * 一次干净、一次夹带推理,非确定性)。开启后会用一组特征词与
         * 格式特征把这类内容尽量剔除。
         */
        private boolean stripReasoningLeak = false;
 
        /** 额外的自定义请求头(某些网关需要,如 X-Api-Key) */
        private java.util.Map<String, String> extraHeaders = new java.util.HashMap<>();
    }
 
    @Data
    public static class Defaults {
        private Double temperature = 0.7;
        private Double topP = 0.9;
        private Integer numCtx = 8192;
    }
}