From dda2e040ca5cb1ad2f80ac013405fba50f902435 Mon Sep 17 00:00:00 2001
From: Nelson <1475262689@qq.com>
Date: Mon, 13 Jul 2026 15:17:09 +0800
Subject: [PATCH] feat: explain agent generation parameters

---
 .../src/components/AgentManagementView.vue    | 30 ++++++++++++++----
 .../apps/admin-web/src/main.ts                |  3 ++
 .../apps/admin-web/src/styles.css             | 31 +++++++++++++++++++
 3 files changed, 58 insertions(+), 6 deletions(-)

diff --git a/ai_knowledge_base_v2/apps/admin-web/src/components/AgentManagementView.vue b/ai_knowledge_base_v2/apps/admin-web/src/components/AgentManagementView.vue
index 86797d8..e0d4c17 100644
--- a/ai_knowledge_base_v2/apps/admin-web/src/components/AgentManagementView.vue
+++ b/ai_knowledge_base_v2/apps/admin-web/src/components/AgentManagementView.vue
@@ -302,12 +302,30 @@ function errorMessage(error: unknown, fallback: string) {
             <section class="agent-advanced-settings">
               <div class="agent-subsection-title"><h4>高级生成参数</h4><span>仅影响本次后台调试</span></div>
               <div class="agent-config-grid">
-                <el-form-item label="回答随机性"><el-input-number v-model="agentForm.temperature" :min="0" :max="2" :step="0.1" /></el-form-item>
-                <el-form-item label="核采样概率"><el-input-number v-model="agentForm.topP" :min="0" :max="1" :step="0.05" /></el-form-item>
-                <el-form-item label="候选词数量"><el-input-number v-model="agentForm.topK" :min="1" :max="1000" /></el-form-item>
-                <el-form-item label="最大输出长度"><el-input-number v-model="agentForm.maxToken" :min="1" :max="100000" /></el-form-item>
-                <el-form-item label="主题重复惩罚"><el-input-number v-model="agentForm.presencePenalty" :min="-2" :max="2" :step="0.1" /></el-form-item>
-                <el-form-item label="高频重复惩罚"><el-input-number v-model="agentForm.frequencyPenalty" :min="-2" :max="2" :step="0.1" /></el-form-item>
+                <el-form-item>
+                  <template #label><span class="agent-parameter-label">回答随机性<el-tooltip placement="top" :show-after="200" content="取值 0–2。数值越小，回答越稳定、一致；数值越大，表达越多样，但也更容易发散。答疑场景建议使用较低数值。"><button type="button" class="agent-parameter-help" aria-label="回答随机性说明">?</button></el-tooltip></span></template>
+                  <el-input-number v-model="agentForm.temperature" :min="0" :max="2" :step="0.1" />
+                </el-form-item>
+                <el-form-item>
+                  <template #label><span class="agent-parameter-label">核采样概率<el-tooltip placement="top" :show-after="200" content="取值 0–1。模型只从累计概率达到该数值的候选词中选择。数值越小越专注，越大越多样。留空表示使用模型供应商默认值。"><button type="button" class="agent-parameter-help" aria-label="核采样概率说明">?</button></el-tooltip></span></template>
+                  <el-input-number v-model="agentForm.topP" :min="0" :max="1" :step="0.05" />
+                </el-form-item>
+                <el-form-item>
+                  <template #label><span class="agent-parameter-label">候选词数量<el-tooltip placement="top" :show-after="200" content="取值 1–1000。每次生成只从概率最高的前 K 个候选词中选择。数值越小越保守，越大选择越多。留空表示使用供应商默认值，部分模型可能不支持。"><button type="button" class="agent-parameter-help" aria-label="候选词数量说明">?</button></el-tooltip></span></template>
+                  <el-input-number v-model="agentForm.topK" :min="1" :max="1000" />
+                </el-form-item>
+                <el-form-item>
+                  <template #label><span class="agent-parameter-label">最大输出长度<el-tooltip placement="top" :show-after="200" content="限制模型本次最多生成的 Token 数，不等于字数，也不代表一定会生成到该长度。数值越大允许回答越长，同时可能增加耗时和费用，最终仍受模型上限约束。"><button type="button" class="agent-parameter-help" aria-label="最大输出长度说明">?</button></el-tooltip></span></template>
+                  <el-input-number v-model="agentForm.maxToken" :min="1" :max="100000" />
+                </el-form-item>
+                <el-form-item>
+                  <template #label><span class="agent-parameter-label">主题重复惩罚<el-tooltip placement="top" :show-after="200" content="取值 -2–2，0 表示不调整。正数会降低已出现内容再次出现的概率，鼓励引入新主题；负数会更容易重复已出现内容。数值过高可能导致回答跳跃。"><button type="button" class="agent-parameter-help" aria-label="主题重复惩罚说明">?</button></el-tooltip></span></template>
+                  <el-input-number v-model="agentForm.presencePenalty" :min="-2" :max="2" :step="0.1" />
+                </el-form-item>
+                <el-form-item>
+                  <template #label><span class="agent-parameter-label">高频重复惩罚<el-tooltip placement="top" :show-after="200" content="取值 -2–2，0 表示不调整。正数会根据词语已出现的次数降低其再次出现的概率，用于减少反复表达；负数会增加重复倾向。数值过高可能影响语句连贯性。"><button type="button" class="agent-parameter-help" aria-label="高频重复惩罚说明">?</button></el-tooltip></span></template>
+                  <el-input-number v-model="agentForm.frequencyPenalty" :min="-2" :max="2" :step="0.1" />
+                </el-form-item>
               </div>
             </section>
           </el-form>
diff --git a/ai_knowledge_base_v2/apps/admin-web/src/main.ts b/ai_knowledge_base_v2/apps/admin-web/src/main.ts
index 8028f33..1399661 100644
--- a/ai_knowledge_base_v2/apps/admin-web/src/main.ts
+++ b/ai_knowledge_base_v2/apps/admin-web/src/main.ts
@@ -25,6 +25,7 @@ import {
   ElTableColumn,
   ElTabs,
   ElTag,
+  ElTooltip,
   vLoading,
 } from "element-plus";
 import "element-plus/theme-chalk/base.css";
@@ -54,6 +55,7 @@ import "element-plus/theme-chalk/el-switch.css";
 import "element-plus/theme-chalk/el-table.css";
 import "element-plus/theme-chalk/el-tabs.css";
 import "element-plus/theme-chalk/el-tag.css";
+import "element-plus/theme-chalk/el-tooltip.css";
 import { createApp } from "vue";
 import zhCn from "element-plus/es/locale/lang/zh-cn";
 
@@ -90,6 +92,7 @@ app.config.globalProperties.$ELEMENT = { locale: zhCn };
   ElTableColumn,
   ElTabs,
   ElTag,
+  ElTooltip,
 ].forEach((component) => {
   app.use(component);
 });
diff --git a/ai_knowledge_base_v2/apps/admin-web/src/styles.css b/ai_knowledge_base_v2/apps/admin-web/src/styles.css
index e71f119..904f9f4 100644
--- a/ai_knowledge_base_v2/apps/admin-web/src/styles.css
+++ b/ai_knowledge_base_v2/apps/admin-web/src/styles.css
@@ -741,6 +741,37 @@ textarea {
   font-size: 12px;
 }
 
+.agent-parameter-label {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.agent-parameter-help {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 17px;
+  height: 17px;
+  padding: 0;
+  border: 1px solid #9aaca6;
+  border-radius: 50%;
+  background: #ffffff;
+  color: #60746d;
+  font-size: 11px;
+  font-weight: 700;
+  line-height: 1;
+  cursor: help;
+}
+
+.agent-parameter-help:hover,
+.agent-parameter-help:focus-visible {
+  border-color: #0f735d;
+  color: #0f735d;
+  outline: none;
+  box-shadow: 0 0 0 2px rgba(15, 115, 93, 0.14);
+}
+
 .agent-trace-wide {
   grid-column: 1 / -1;
   height: 420px;