Files
AgentLab/backend/app/engine/provider_refs.py
T
ThearchyHelios 4673e51bb8 模型接入报错的说法与修复候选收尾(后端):修复规划只否决这次改动造成的失败、问题只认自己那一处的修复、没有修复时提示不指到发布前检查、落到演示类接入照实说;各处说法对齐
修复规划(autofix.provider_choice,原 _plan_provider 的主体,provider_refs 也用它判断给不给得出修复):
- 改动波及的一处,要是点名的接入没变、而那个接入本来就不存在或已停用,它落不稳不是这次改动造成的,不再拿它否决候选。
  以前两处互相牵连(节点点名的接入写错、模型取全图默认里停用接入的模型)时两条问题都没有修复,规划器自己卡住;
- 点名的模型接入一处一条修复,annotate 只认(编号、节点、字段)都对得上的那一条,认不出就是没有,不再退到同节点、
  同编号别处的修复(以前全图默认那条的 fix 会指到某个节点的修复上);
- 一个候选都落不稳时,问题提示不再写「或在「发布前检查」中改用其他接入」,只说去设置里核对、启用;
- 修完以后落到演示类接入(kind 为 mock)时,「不指定接入」的说明写明「演示用,不调用真实模型」,和「改用演示接入」
  那一项一致——K1 要防的就是悄悄换成演示模型。

说法:
- 双盲复算、反方审稿的问题写「……的「盲算模型 · 接入」指定的模型接入」,不说「盲算模型指定的接入」(修复标题仍按角色说);
- 点名的接入名恰好是某个启用接入的模型时,运行时报错、画布问题、保存设置的 422、助手的报错都补一句这是哪个接入的
  模型、怎么用它(factory.model_note;设置页写那一组模型、接入两栏的叫法),免得照「启用它」去启用那条旧接入;
- 保存设置 422:下拉框选的写「指定的」,不写「填写的」;去掉和设置页空选项对不上的留空半句;助手那一项叫「助手使用的
  模型」;核查的格式检查写「留空表示跟随证据裁判模型」,同设置页;
- 「交给助手」后只剩接入问题时的说明:一句一个意思、不再带冒号(界面上前面已有「助手:」),「核对名称」有宾语,不说
  「节点」;有一条带修复时才指到各条问题的修复;
- 助手的模型取不到时,提示指到真正能改的地方:「编排」页助手栏的「助手使用的模型」(设置页没有这一项);
- 节点点名了接入、没写模型时校验说「将使用接入「X」的默认模型」(编号 model.unset);X 本身不存在或已停用时画布校验、
  发布一类都去掉这一条,只留接入那条,不再一条说照常执行、一条说会失败。
2026-10-06 17:29:18 +08:00

317 lines
19 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""工作流里点名的模型接入:不存在或已停用的,画布校验、发布前检查、发布时照实提出来。
运行时点名的接入不存在或已停用直接报错(providers/factory.named_provider),以前是悄悄换成演示模型。这类问题发布前
就该看得到:画布校验给警告(探索运行仍可发起,执行到那里报错),发布、发布前检查、自动修复的复核给错误、挡住
发布——正式运行到那里一定失败,或者少一块核查。
查的是执行时真会去取模型的那几处,取法和执行器一致(uses):
- 模型调用、Agent、报告撰写、多 Agent 协作的接入;条件分支只在「让模型分类」时、结构校验只在「让模型修复」且允许
重试时(max_retries 为 0 一次都不修)、知识检索只在「让模型重排」时才取模型。这几类节点没写自己的接入、模型时
各自取全图默认(NodeContext.cfg);
- 多 Agent 协作各成员:自己没写的接入、模型各自跟随节点(再到全图默认,nodes/multi._member);报告撰写交给模型
裁判结论句时,「结论句裁判」里的接入、模型(节点没写裁判配置时取全图默认里的那一份,同 nodes/report.report_judge);
- 双盲复算、反方审稿的接入、模型(核查模型):只读节点自己的配置,不取全图默认。节点自己的开关关着时执行器直接
跳过、不取模型,不查;设置里的总开关不看——它随时会被打开,打开时这一处就会失败;
- 全图默认的接入、模型:有节点会取到它时才查。
取到了接入的,查点名的那个接入(不存在、已停用);哪一级都没写接入、只写了模型的,按模型名找接入,只有停用的接入
提供它时同样是问题(provider.disabled,落在写模型的那一处)——运行时 resolve_provider 报的就是这一句,而多数节点的
检查器里只能选模型,这是最常见的写法。核查、裁判的接入、模型都没写时交给设置,不归这里查。
说法分两种:检查器里有这一项下拉框的几处(双盲复算、反方审稿、节点自己的结论句裁判的接入和模型,几类节点自己的模型)
说「在节点中换一个接入 / 模型」;别处(节点自己的接入、协作成员、全图默认)界面上没有下拉框,说「在发布前检查中改用
其他接入」——发布前检查给这类问题配了修复(engine/autofix.py 的 provider.*:改用一个启用的接入,或不再指定),修复
按 land 算出修完以后执行时落到哪里,落不稳的候选不给。一个候选都落不稳时修复为空,这时不指到发布前检查(那里什么
都不给),只说去设置里核对、启用。点名的名字恰好是某个启用接入的模型时,末尾补一句这是哪个接入的模型
(factory.model_note)。
节点没写模型、点名的接入(自己的或全图默认的)本身不存在或已停用时,校验那条「没有指定模型,将使用接入「X」的
默认模型」(schema.MODEL_UNSET)和这里的问题互相矛盾,由 quiet_unset_model 去掉前者。
接入表要读库,门禁本身不查库(governance.lint_for_publish),所以由接口这一层读出接入表交进来,同数据目录
SQL 检查器的做法。设置里点名接入的几项由 api/settings.py 在保存时查。
"""
from __future__ import annotations
from dataclasses import dataclass
from typing import Any, Callable
from sqlalchemy.ext.asyncio import AsyncSession
from app.engine.labels import field_label, type_label
from app.engine.schema import CLAIMS_JUDGE, MODEL_UNSET, GraphNode, GraphSpec, NodeType, ValidationIssue
from app.providers.factory import (
NAMED_FIX, ProviderNotConfigured, fallback_provider, list_providers, model_note, named_provider,
provider_for_model, serves,
)
#: 这类问题的编号:provider.missing(点名的接入不存在)、provider.disabled(已停用;只写了模型、提供它的接入停用了也是它)
CODES = frozenset({"provider.missing", "provider.disabled"})
#: 提示的后半句:这一处写的是接入还是模型、检查器里有没有这一项的下拉框。检查器里没有下拉框的,发布前检查给了修复
#: 才指到那里(IN_CHECK),否则不写后半句
_WHERE = {"provider": "或在节点中换一个接入", "model": "或在节点中换一个模型"}
IN_CHECK = "或在「发布前检查」中改用其他接入"
#: 修完以后执行时落到演示类接入(kind 为 mock):说明里照实写。K1 要防的就是悄悄换成演示模型——落到它是人选的,
#: 得让人知道选的是什么
DEMO_LANDING = "(演示用,不调用真实模型)"
#: 检查器里有模型下拉框的几类节点(前端 nodeDefs 的 MODEL_FIELDS;条件分支只在「让模型分类」时显示,也只在那时才查)
_MODEL_PICKER = frozenset({NodeType.LLM, NodeType.AGENT, NodeType.SUPERVISOR, NodeType.BRANCH, NodeType.REPORT})
#: 核查、裁判的接入和模型都没写时执行用设置里的哪一项(api/settings.verify_model_spec、judge.judge_model_spec)
_SETTINGS = {"verify": "设置中的核查模型", "judge": "设置中的裁判模型"}
def _cfg(spec: GraphSpec, node: GraphNode, key: str, default: Any = None) -> Any:
"""和 NodeContext.cfg 同一个规则:节点上没写(None、空串)就取全图默认。"""
value = node.config.get(key)
return spec.defaults.get(key, default) if value in (None, "") else value
def _repairs(spec: GraphSpec, node: GraphNode) -> bool:
"""结构校验会不会让模型修复:允许修复,而且至少重试一次(nodes/human.run_validate 同一个取值)。认不出的重试次数
按会修复算:执行时它照样报错,这里宁可多提一句。"""
if not _cfg(spec, node, "repair_with_llm", True):
return False
try:
return int(_cfg(spec, node, "max_retries", 2) or 0) > 0
except (TypeError, ValueError):
return True
#: 按 NodeContext.cfg 取接入的节点 → 执行时真会去取模型的条件(None 是总会取)
_TAKES_MODEL: dict[NodeType, Callable[[GraphSpec, GraphNode], bool] | None] = {
NodeType.LLM: None,
NodeType.AGENT: None,
NodeType.REPORT: None,
NodeType.SUPERVISOR: None,
NodeType.BRANCH: lambda spec, node: _cfg(spec, node, "mode", "expression") == "llm",
NodeType.VALIDATE: _repairs,
NodeType.RETRIEVE: lambda spec, node: _cfg(spec, node, "rerank", "off") == "model",
}
#: 核查节点:接入只读节点自己的配置(verify_model_spec),图级默认的接入是写作模型的。值是修复标题里的称呼
#:(「选择……的盲算模型改用的模型接入」);问题里说「……的「盲算模型 · 接入」指定的」,写检查器上那一栏的叫法
_VERIFY = {NodeType.DUAL_CHECK: "的盲算模型", NodeType.CHALLENGE: "的反方模型"}
def _name(value: Any) -> str | None:
return value.strip() or None if isinstance(value, str) else None
@dataclass(frozen=True)
class ProviderRef:
"""图里写着接入或模型的一处:落在哪个节点(全图默认为 None)、哪个字段,写的名字,句子里怎么称呼这一处,检查器里
有没有这一项的下拉框;kind 是写的接入(provider)还是模型(model)。
who 是修复标题里的称呼(「选择{who}改用的模型接入」);said 是「{said}指定的模型接入「X」」里的主语,默认同 who。
核查节点两者不同:指定接入的是「盲算模型 · 接入」这一栏,不是盲算模型本身。"""
node_id: str | None
field: str
name: str
who: str
editable: bool = False
kind: str = "provider"
said: str = ""
@property
def subject(self) -> str:
return self.said or self.who
def _place(node_id: str | None, field: str, value: Any, who: str, *, editable: bool = False,
kind: str = "provider", said: str = "") -> ProviderRef | None:
name = _name(value)
return ProviderRef(node_id, field, name, who, editable, kind, said) if name else None
@dataclass(frozen=True)
class Use:
"""执行时取一次模型:key 是(节点 id,哪一次:node、agents[i]、judge、verify),who 是句子里怎么称呼它;接入、模型
各取自哪一处(哪一级都没写为 None)。settings 是核查、裁判的接入和模型都没写、交给设置的那一项(verify / judge)。"""
key: tuple[str, str]
who: str
provider: ProviderRef | None
model: ProviderRef | None
settings: str | None = None
def _own_or_default(spec: GraphSpec, node: GraphNode, key: str, who: str) -> ProviderRef | None:
"""节点的 provider / model 取自哪一处,同 NodeContext.cfg:节点上没写(None、空串)就取全图默认。"""
if node.config.get(key) in (None, ""):
return _place(None, f"defaults.{key}", spec.defaults.get(key), field_label("defaults"), kind=key)
return _place(node.id, key, node.config.get(key), who, kind=key,
editable=key == "model" and node.type in _MODEL_PICKER)
def uses(spec: GraphSpec) -> list[Use]:
"""图里执行时取模型的每一处,按画布上节点的顺序;只算执行时真会取模型的(见模块说明)。"""
out: list[Use] = []
for node in spec.nodes:
cfg = node.config
who = f"「{node.title}」({type_label(node.type)})"
if node.type in _VERIFY:
# 接入、模型哪一项写了就整组以节点为准,都没写交给设置(verify_model_spec)
if cfg.get("enabled") is not False:
vwho = who + _VERIFY[node.type]
p = _place(node.id, "provider", cfg.get("provider"), vwho, editable=True,
said=f"{who}的「{field_label('provider', node.type)}」")
m = _place(node.id, "model", cfg.get("model"), vwho, editable=True, kind="model",
said=f"{who}的「{field_label('model', node.type)}」")
out.append(Use((node.id, "verify"), vwho, p, m, None if p or m else "verify"))
continue
if node.type not in _TAKES_MODEL:
continue
provider, model = _own_or_default(spec, node, "provider", who), _own_or_default(spec, node, "model", who)
cond = _TAKES_MODEL[node.type]
if cond is None or cond(spec, node):
out.append(Use((node.id, "node"), who, provider, model))
if node.type == NodeType.SUPERVISOR and isinstance(cfg.get("agents"), list):
# 成员自己写了(非空)就用自己的,否则跟随节点,同 nodes/multi._member 的 `cfg.get(...) or ctx.cfg(...)`
for i, member in enumerate(cfg["agents"]):
if not isinstance(member, dict):
continue
label = _name(member.get("name")) or f"第 {i + 1} 位"
mwho = f"{who}的成员「{label}」"
own_p, own_m = member.get("provider"), member.get("model")
out.append(Use((node.id, f"agents[{i}]"), mwho,
_place(node.id, f"agents[{i}].provider", own_p, mwho) if own_p else provider,
_place(node.id, f"agents[{i}].model", own_m, mwho, kind="model") if own_m else model))
if node.type == NodeType.REPORT and _cfg(spec, node, "claims", "off") == CLAIMS_JUDGE:
judge = _cfg(spec, node, "judge")
# 节点没写裁判配置,执行时用全图默认里的那一份:问题记在全图默认上,几个报告共用时只记一条
own = judge is cfg.get("judge")
nid, at, jwho = (node.id, "judge", f"{who}的{field_label('judge')}") if own else \
(None, "defaults.judge", f"{field_label('defaults')}中的{field_label('judge')}")
judge = judge if isinstance(judge, dict) else {}
p = _place(nid, f"{at}.provider", judge.get("provider"), jwho, editable=own)
m = _place(nid, f"{at}.model", judge.get("model"), jwho, editable=own, kind="model")
out.append(Use((node.id, "judge"), jwho, p, m, None if p or m else "judge"))
return out
def provider_refs(spec: GraphSpec) -> list[ProviderRef]:
"""执行时要查的那几处,按画布上节点的顺序,全图默认排最后,同一处只记一次:取到了接入的是那个接入;哪一级都没写
接入、只写了模型的是那个模型(按模型名找接入)。"""
found: dict[tuple[str | None, str], ProviderRef] = {}
for use in uses(spec):
if (ref := use.provider or use.model) is not None:
found.setdefault((ref.node_id, ref.field), ref)
return sorted(found.values(), key=lambda r: r.node_id is None)
def broken(refs: list[ProviderRef], providers: list[Any]) -> list[tuple[ProviderRef, ProviderNotConfigured]]:
"""执行时会报错的那几处,带着运行时报的那个错(code 是 missing / disabled):点名的接入按名字找(named_provider),
只写了模型的按模型名找(provider_for_model,认不出的模型名运行时放行,不算)。"""
out: list[tuple[ProviderRef, ProviderNotConfigured]] = []
for ref in refs:
try:
if ref.kind == "model":
provider_for_model(providers, ref.name)
else:
named_provider(providers, ref.name)
except ProviderNotConfigured as e:
out.append((ref, e))
return out
def _tail(spec: GraphSpec, ref: ProviderRef, providers: list[Any]) -> str:
"""提示的后半句:检查器里有这一项的下拉框,指到节点;没有的,发布前检查给得出修复才指到那里——一个候选都落不稳
时(比如一个启用的接入都没有,或者改动波及的别处都落不稳)那里什么都不给,指过去只会让人白找。"""
if ref.editable:
return f",{_WHERE[ref.kind]}"
# 在这里导入:autofix 导入了门禁(governance),门禁又在 lint_for_publish 里导入本模块
from app.engine.autofix import provider_choice
return f",{IN_CHECK}" if provider_choice(spec, ref, providers) is not None else ""
def issues(spec: GraphSpec, providers: list[Any], *, level: str) -> list[ValidationIssue]:
"""执行时会报错的每一处一条问题。providers 是接入表(factory.list_providers),level 由调用方定:画布校验 warning,
发布一类 error。原因和运行时报的同一句,提示按这一处在界面上能不能改(_tail);点名的名字恰好是某个启用接入的
模型时补一句(factory.model_note)。"""
out = []
for ref, e in broken(provider_refs(spec), providers):
note = f"。{model_note(e.name, e.model_owner)}" if e.model_owner else ""
out.append(ValidationIssue(level=level, node_id=ref.node_id, field=ref.field, # type: ignore[arg-type]
code=f"provider.{e.code}",
message=f"{ref.subject}指定的{e.reason}。{NAMED_FIX[e.code]}"
f"{_tail(spec, ref, providers)}{note}"))
return out
def quiet_unset_model(spec: GraphSpec, found: list[Any], provider_issues: list[Any]) -> list[Any]:
"""去掉被接入问题盖住的「没有指定模型,将使用接入「X」的默认模型」(schema.MODEL_UNSET)。
节点没写模型、取到的接入(自己点名的,没写就是全图默认点名的,同 NodeContext.cfg)本身不存在或已停用时,那条说
会用 X 的默认模型照常执行,接入那一条说执行到这里会失败,读者无从判断哪条是真的。接入那一条带着原因和改法,留它。
found 是校验的问题(ValidationIssue),provider_issues 是 issues() 的结果;画布校验和发布一类各调一次。"""
hit = {(i.node_id, i.field) for i in provider_issues if i.code in CODES}
if not hit:
return found
nodes = spec.node_map()
def covered(issue: Any) -> bool:
if issue.code != MODEL_UNSET or (node := nodes.get(issue.node_id)) is None:
return False
own = node.config.get("provider") not in (None, "")
return ((node.id, "provider") if own else (None, "defaults.provider")) in hit
return [i for i in found if not covered(i)]
@dataclass(frozen=True)
class Landing:
"""执行时这一处落到哪里:where 是说给人听的(「工作流默认设置指定的接入「甲」」……),model 是用哪个模型(交给设置时
为 None),ok 是修复能不能把它落在这里。落到演示类接入时 where 末尾带着 DEMO_LANDING。"""
where: str
model: str | None
ok: bool
def land(use: Use, providers: list[Any]) -> Landing:
"""按执行器的取法(get_chat_model → resolve_provider → build_chat_model)算这一处执行时用哪个接入、哪个模型。
ok 为真才算落得稳:点名的接入启用着、有模型可用,并且提供这一处写的模型——拿 A 家的模型名去调 B 家必然失败;
只写了模型的,按模型名找到启用的接入。按模型名落到停用的接入(运行时报错)、模型名认不出来(落到第一个可用的
接入,它多半不提供)、一个启用的接入都没有(悄悄换成内置演示模型)都不算。交给设置的(核查、裁判)算落得稳:
设置保存时查过点名的接入,之后接入出了问题设置页会标出来。"""
if use.settings:
return Landing(_SETTINGS[use.settings], None, True)
model = use.model.name if use.model is not None else None
if use.provider is not None:
try:
found = named_provider(providers, use.provider.name)
except ProviderNotConfigured as e:
return Landing(e.reason, model, False)
where = f"{use.provider.subject}指定的接入「{found.name}」"
elif model:
try:
found = provider_for_model(providers, model)
except ProviderNotConfigured as e:
return Landing(e.reason, model, False)
if found is None:
return Landing(f"认不出的模型「{model}」", model, False)
where = f"提供模型「{model}」的接入「{found.name}」"
else:
found = fallback_provider(providers)
if found is None:
return Landing("内置演示模型", None, False)
where = f"第一个可用的模型接入「{found.name}」"
if getattr(found, "kind", None) == "mock":
where += DEMO_LANDING
used = model or found.default_model
return Landing(where, used, bool(used) and (model is None or serves(found, model)))
async def load_issues(session: AsyncSession, spec: GraphSpec, *, level: str) -> list[ValidationIssue]:
"""读接入表、查一遍。图里执行时取模型的几处都没写接入和模型时不读库。"""
if not provider_refs(spec):
return []
return issues(spec, await list_providers(session), level=level)
async def load_providers(session: AsyncSession, spec: GraphSpec) -> list[Any] | None:
"""发布、发布前检查、自动修复交给门禁的接入表(governance.lint_for_publish 的 providers)。图里执行时取模型的几处
都没写接入和模型时不读库,给空表:没有要查的,修复也用不上候选。"""
return await list_providers(session) if provider_refs(spec) else []