feat(skills,knowledge): 中文名补全与知识库沉淀支持可选大模型并明确大模型报错

技能中文名:
- 单个「AI 生成」与「一键补充中文名」均可在请求体 model_name 选择大模型
- 一键补充改为仅管理员开放
- _generate_skill_name_zh 在模型自身失败(构建/超时/API 报错)时抛
  SkillNameZhModelError,与模型返回无效名称区分;单个接口返回
  502「大模型报错,无法补全技能中文名」,批量在 model_error 中带回代表性报错

知识库沉淀:
- 对话保存到知识库 / 批量导入均新增可选 model_name(透传至 capture_thread
  → extract_thread_llm_multi)
- 批量返回 llm_fallback 计数;模型异常时仍按既有逻辑回退规则抽取并落草稿,
  前端明确提示「已改用规则抽取」(保存按钮保持后台异步)

前端新增 components/workspace/model-name-select.tsx 复用下拉(默认=系统配置模型)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
吉鑫升andClaude Opus 4.8 committed 2026-06-10 11:23:01 +08:00
1 parent 8fbbfc8093
commit 96e0d695c0
11 files changed
+295 -83

No files matched your search

@@ -44,6 +44,7 @@ class IngestThreadRequest(BaseModel):
default=False,
description="When true, sediment the thread asynchronously in a background task and return immediately.",
)
model_name: str | None = Field(default=None, description="可选:指定用于知识提炼的大模型名称;留空使用默认配置")
class BatchIngestRequest(BaseModel):
@@ -53,6 +54,7 @@ class BatchIngestRequest(BaseModel):
include_sources: bool = True
skip_existing: bool = True
mode: str = "summary"
model_name: str | None = Field(default=None, description="可选:指定用于知识提炼的大模型名称;留空使用默认配置")
class SearchResultItem(BaseModel):
@@ -175,6 +177,7 @@ async def _ingest_thread_background(service, checkpointer, thread_id: str, body:
include_sources=body.include_sources,
reference_batches=batches,
created_by=created_by,
model_name=body.model_name,
)
except EmptyThreadError:
logger.warning("Background knowledge ingest skipped: thread %s has no sediment-able content", sanitize_log_param(thread_id))
@@ -224,6 +227,7 @@ async def ingest_thread(thread_id: str, body: IngestThreadRequest, request: Requ
include_sources=body.include_sources,
reference_batches=batches,
created_by=get_effective_user_id(),
model_name=body.model_name,
)
except EmptyThreadError:
raise HTTPException(status_code=400, detail="Thread has no sediment-able content")
@@ -245,6 +249,10 @@ async def ingest_threads_batch(body: BatchIngestRequest, request: Request) -> di
threads = await thread_store.search(limit=body.limit, offset=body.offset)
created = skipped = failed = 0
# Notes that landed via the rule-based fallback because the chosen model
# produced nothing usable (timeout / API error / non-JSON). Surfaced so the
# caller can tell the user "X 条因大模型异常改用了规则抽取".
llm_fallback = 0
items: list[dict[str, Any]] = []
for meta in threads:
thread_id = meta.get("thread_id")
@@ -267,10 +275,13 @@ async def ingest_threads_batch(body: BatchIngestRequest, request: Request) -> di
reference_batches=batches,
created_by=get_effective_user_id(),
skip_existing=body.skip_existing,
model_name=body.model_name,
)
if result.get("llm_fallback"):
llm_fallback += 1
if result["created"]:
created += 1
items.append({"thread_id": thread_id, "note_id": result["note"]["id"], "status": "created"})
items.append({"thread_id": thread_id, "note_id": result["note"]["id"], "status": "created", "llm_fallback": bool(result.get("llm_fallback"))})
else:
skipped += 1
items.append({"thread_id": thread_id, "note_id": result["note"]["id"], "status": "skipped"})
@@ -285,7 +296,7 @@ async def ingest_threads_batch(body: BatchIngestRequest, request: Request) -> di
failed += 1
items.append({"thread_id": thread_id, "note_id": None, "status": "failed"})
return {"ok": True, "processed": len(items), "created": created, "skipped": skipped, "failed": failed, "items": items}
return {"ok": True, "processed": len(items), "created": created, "skipped": skipped, "failed": failed, "llm_fallback": llm_fallback, "items": items}
@router.post("/ingest/search")
@@ -2366,6 +2366,15 @@ _SKILL_NAME_ZH_SYSTEM_PROMPT = (
)
class SkillNameZhModelError(Exception):
"""The LLM call backing skill-name generation failed (a *model-side* problem).
Distinguishes a genuine model failure (timeout / API error / unbuildable
model) — which must be surfaced to the user as "大模型报错导致无法补全" — from
the model merely returning an unusable name (callers get ``None`` instead).
"""
def _clean_generated_name_zh(raw: str) -> str | None:
"""Normalise an LLM-produced Chinese name: first line, strip quotes/punct, cap length."""
if not raw:
@@ -2388,24 +2397,45 @@ def _clean_generated_name_zh(raw: str) -> str | None:
return text or None
async def _generate_skill_name_zh(skill: Skill, app_config: AppConfig, model: Any = None) -> str | None:
def _resolve_skill_name_zh_model_name(app_config: AppConfig, model_name: str | None) -> str | None:
"""Pick the model name for skill-name generation.
An explicit ``model_name`` (user-selected in the UI) wins; otherwise fall
back to the curator/security-scan model setting (itself falling back to the
main model when unset).
"""
if model_name and model_name.strip():
return model_name.strip()
if app_config.skill_evolution and app_config.skill_evolution.curator:
return app_config.skill_evolution.curator.model_name
return None
async def _generate_skill_name_zh(skill: Skill, app_config: AppConfig, model: Any = None, *, model_name: str | None = None) -> str | None:
"""Generate a Chinese display name for ``skill`` via the LLM.
Reuses the curator/security-scan model setting (falls back to the main model).
Returns None when the model is unconfigured, the call times out/fails, or the
output cannot be normalised into a short Chinese name.
An explicit ``model_name`` lets the caller pick the model; otherwise it
reuses the curator/security-scan model setting (falls back to the main
model). Returns ``None`` only when the model replies but the output cannot be
normalised into a short Chinese name. Raises :class:`SkillNameZhModelError`
when the model itself fails (cannot be built / times out / API error), so the
caller can tell the user it was a *model* problem.
"""
user_prompt = (
f"技能英文名:{skill.name}\n"
f"功能描述:{skill.description or '(无描述)'}\n\n"
"请为该技能起一个中文名称。"
)
try:
from deerflow.models import create_chat_model
if model is None:
try:
from deerflow.models import create_chat_model
if model is None:
model_name = app_config.skill_evolution.curator.model_name if app_config.skill_evolution and app_config.skill_evolution.curator else None
model = create_chat_model(name=model_name, thinking_enabled=False, app_config=app_config)
resolved = _resolve_skill_name_zh_model_name(app_config, model_name)
model = create_chat_model(name=resolved, thinking_enabled=False, app_config=app_config)
except Exception as e:
logger.warning("Skill name_zh model build failed for %s", skill.name, exc_info=True)
raise SkillNameZhModelError(str(e) or "无法初始化所选大模型") from e
try:
response = await asyncio.wait_for(
model.ainvoke(
[
@@ -2416,12 +2446,13 @@ async def _generate_skill_name_zh(skill: Skill, app_config: AppConfig, model: An
),
timeout=30,
)
return _clean_generated_name_zh(str(getattr(response, "content", "") or ""))
except asyncio.TimeoutError:
except asyncio.TimeoutError as e:
logger.warning("Skill name_zh LLM call timed out for %s", skill.name)
except Exception:
raise SkillNameZhModelError("大模型响应超时(30 秒)") from e
except Exception as e:
logger.warning("Skill name_zh LLM call failed for %s", skill.name, exc_info=True)
return None
raise SkillNameZhModelError(str(e) or "大模型调用失败") from e
return _clean_generated_name_zh(str(getattr(response, "content", "") or ""))
async def _persist_skill_name_zh(
@@ -2475,6 +2506,13 @@ class SkillNameZhBulkResponse(BaseModel):
generated: list[SkillNameZhResponse] = Field(default_factory=list, description="本次成功生成中文名的技能")
failed: list[str] = Field(default_factory=list, description="生成失败的技能英文名")
skipped: int = Field(default=0, description="已有中文名而被跳过的技能数")
model_error: str | None = Field(default=None, description="若有技能因大模型报错而失败,这里给出代表性的报错信息")
class GenerateSkillNameZhRequest(BaseModel):
"""Optional body for skill-name generation: pick the model to use."""
model_name: str | None = Field(default=None, description="可选:指定用于生成的大模型名称;留空使用默认配置")
def _can_edit_skill_name_zh(skill: Skill, record: dict[str, Any] | None, user_id: str, *, is_admin: bool) -> bool:
@@ -2521,15 +2559,17 @@ async def set_skill_name_zh(
"/skills/{skill_name}/name-zh/generate",
response_model=SkillNameZhResponse,
summary="Generate Skill Chinese Name",
description="用大模型为该技能生成一个中文名称并保存到数据库。",
description="用大模型为该技能生成一个中文名称并保存到数据库。可在请求体里通过 model_name 指定使用的大模型。",
)
async def generate_skill_name_zh(
skill_name: str,
request: Request,
body: GenerateSkillNameZhRequest | None = None,
config: AppConfig = Depends(get_config),
skill_store: SkillStore = Depends(get_skill_store),
) -> SkillNameZhResponse:
try:
body = body or GenerateSkillNameZhRequest()
skill_name = skill_name.replace("\r\n", "").replace("\n", "")
user_id = _current_user_id(request)
is_admin = _is_admin_user(request)
@@ -2537,9 +2577,12 @@ async def generate_skill_name_zh(
skill = next((s for s in skills if s.name == skill_name), None)
if skill is None:
raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
name_zh = await _generate_skill_name_zh(skill, config)
try:
name_zh = await _generate_skill_name_zh(skill, config, model_name=body.model_name)
except SkillNameZhModelError as e:
raise HTTPException(status_code=502, detail=f"大模型报错,无法补全技能中文名:{e}")
if not name_zh:
raise HTTPException(status_code=502, detail="模型未能生成有效的中文名称,请稍后重试或手动填写")
raise HTTPException(status_code=502, detail="大模型未能生成有效的中文名称,请稍后重试或手动填写")
stored = await _persist_skill_name_zh(skill, name_zh, skill_store, user_id, is_admin=is_admin)
return SkillNameZhResponse(name=skill_name, name_zh=stored)
except HTTPException:
@@ -2553,26 +2596,27 @@ async def generate_skill_name_zh(
"/skills/name-zh/generate-missing",
response_model=SkillNameZhBulkResponse,
summary="Bulk Generate Missing Skill Chinese Names",
description="一键为库中所有尚未配置中文名称、且当前用户有权编辑的技能生成中文名(存数据库)。",
description="管理员一键为库中所有尚未配置中文名称的技能生成中文名(存数据库)。可在请求体里通过 model_name 指定使用的大模型。",
)
async def generate_missing_skill_names_zh(
request: Request,
body: GenerateSkillNameZhRequest | None = None,
config: AppConfig = Depends(get_config),
skill_store: SkillStore = Depends(get_skill_store),
) -> SkillNameZhBulkResponse:
try:
from deerflow.models import create_chat_model
body = body or GenerateSkillNameZhRequest()
user_id = _current_user_id(request)
is_admin = _is_admin_user(request)
# 一键补充技能中文名仅对管理员开放。
if not is_admin:
raise HTTPException(status_code=403, detail="仅管理员可一键补充技能中文名")
skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
# Existing name_zh values come from the DB. Admins see every row; others
# see only the rows visible to them (owned / published / built-in).
if is_admin:
records = {r["name"]: r for r in await skill_store.list_all()}
else:
records = {r["name"]: r for r in await skill_store.list_visible(user_id)}
# Admin sees every row, so existing name_zh values come from the full set.
records = {r["name"]: r for r in await skill_store.list_all()}
pending: list[Skill] = []
skipped = 0
@@ -2581,32 +2625,36 @@ async def generate_missing_skill_names_zh(
if record and record.get("name_zh"):
skipped += 1
continue
# Skip skills the caller is not allowed to annotate (no error — bulk
# is best-effort over what the user can edit).
if not _can_edit_skill_name_zh(skill, record, user_id, is_admin=is_admin):
continue
pending.append(skill)
generated: list[SkillNameZhResponse] = []
failed: list[str] = []
model_error: str | None = None
if pending:
# Build the model once and reuse it for every skill.
# Build the model once and reuse it for every skill. A build failure
# is a model problem — fail fast with a clear message rather than
# silently producing zero results.
try:
model_name = config.skill_evolution.curator.model_name if config.skill_evolution and config.skill_evolution.curator else None
model = create_chat_model(name=model_name, thinking_enabled=False, app_config=config)
except Exception:
resolved_name = _resolve_skill_name_zh_model_name(config, body.model_name)
model = create_chat_model(name=resolved_name, thinking_enabled=False, app_config=config)
except Exception as e:
logger.warning("Failed to build model for bulk name_zh generation", exc_info=True)
model = None
raise HTTPException(status_code=502, detail=f"大模型报错,无法补全技能中文名:{str(e) or '无法初始化所选大模型'}")
# Generate concurrently with a small bound to avoid overloading the model.
semaphore = asyncio.Semaphore(4)
async def _one(skill: Skill) -> tuple[Skill, str | None]:
async def _one(skill: Skill) -> tuple[Skill, str | None, str | None]:
async with semaphore:
return skill, await _generate_skill_name_zh(skill, config, model=model)
try:
return skill, await _generate_skill_name_zh(skill, config, model=model), None
except SkillNameZhModelError as e:
return skill, None, str(e)
results = await asyncio.gather(*[_one(s) for s in pending])
for skill, name_zh in results:
for skill, name_zh, err in results:
if err and model_error is None:
model_error = err
if not name_zh:
failed.append(skill.name)
continue
@@ -2617,7 +2665,7 @@ async def generate_missing_skill_names_zh(
# Permission / persistence issue for this one skill — skip it.
failed.append(skill.name)
return SkillNameZhBulkResponse(generated=generated, failed=failed, skipped=skipped)
return SkillNameZhBulkResponse(generated=generated, failed=failed, skipped=skipped, model_error=model_error)
except HTTPException:
raise
except Exception as e:
@@ -222,9 +222,13 @@ class KnowledgeService:
reference_batches: list[dict[str, Any]] | None = None,
created_by: str | None = None,
skip_existing: bool = False,
model_name: str | None = None,
) -> dict[str, Any]:
"""Sediment a thread into a knowledge note.
``model_name`` optionally overrides the configured extraction model for
this one capture (falls back to ``config.extract_model_name``).
Returns ``{"note": <note>, "created": bool}``. Raises
:class:`EmptyThreadError` when there is nothing worth keeping.
"""
@@ -269,7 +273,7 @@ class KnowledgeService:
project_name=self.project_name,
sources=sources,
max_messages=self.config.max_thread_messages,
model_name=self.config.extract_model_name,
model_name=model_name or self.config.extract_model_name,
max_input_chars=self.config.extract_max_input_chars,
allow_multi=self.config.multi_note_enabled,
)