sync: 鍚屾灞€鍩熺綉鏈€鏂颁唬鐮?(source master @ b69568e4)

This commit is contained in:
gozeros committed 2026-10-21 14:51:31 +08:00
1 parent 4f7f07504a
commit 8bc8b0e082
1651 files changed
+278599 -11416

No files matched your search

@@ -1,10 +1,16 @@
"""Administrator model configuration backed by DeerFlow's ``config.yaml``.
"""Administrator model configuration and runtime capabilities.
The public ``/api/models`` endpoint intentionally stays small and never
returns secrets. This router is the complementary administrator surface: it
edits only the top-level ``models:`` section in the active DeerFlow config,
keeps a disk backup before every write, and swaps the gateway's runtime config
after validation so new requests can use the change without a restart.
``supports_reasoning_effort`` is deliberately different: it is an
administrator-managed runtime capability persisted in the database, never in
``config.yaml``. The field remains accepted on the general create/update
payload for compatibility with older frontends, while a dedicated endpoint is
the canonical mutation surface.
"""
from __future__ import annotations
@@ -28,8 +34,9 @@ from pydantic import BaseModel, ConfigDict, Field, field_validator
from app.gateway.deps import get_optional_user_from_request
from deerflow.config.app_config import AppConfig, reload_app_config
from deerflow.config.model_config import ModelConfig
from deerflow.config.model_config import ModelConfig, WriteFileTransport
from deerflow.models.factory import create_chat_model
from deerflow.persistence.model_capabilities import ModelCapabilityStore
logger = logging.getLogger(__name__)
router = APIRouter(prefix="/api/admin/models", tags=["admin-models"])
@@ -50,6 +57,7 @@ _EDITOR_FIELDS = frozenset(
"base_url",
"request_timeout",
"max_retries",
"max_input_tokens",
"max_tokens",
"temperature",
"stream_usage",
@@ -61,6 +69,7 @@ _EDITOR_FIELDS = frozenset(
"thinking",
"use_responses_api",
"output_version",
"write_file_transport",
}
)
_PRESERVED_FIELDS = frozenset(ModelConfig.model_fields) | _EDITOR_FIELDS
@@ -77,6 +86,7 @@ class ModelAdminItem(BaseModel):
base_url: str | None = None
request_timeout: float | None = None
max_retries: int | None = None
max_input_tokens: int | None = None
max_tokens: int | None = None
temperature: float | None = None
stream_usage: bool | None = None
@@ -88,6 +98,7 @@ class ModelAdminItem(BaseModel):
thinking: dict[str, Any] | None = None
use_responses_api: bool | None = None
output_version: str | None = None
write_file_transport: WriteFileTransport = WriteFileTransport.NATIVE
extra_settings: dict[str, Any] = Field(default_factory=dict)
api_key_configured: bool = False
api_key_source: str | None = None
@@ -117,17 +128,24 @@ class ModelUpsertRequest(BaseModel):
base_url: str | None = Field(default=None, max_length=2048)
request_timeout: float | None = Field(default=None, ge=1, le=600)
max_retries: int | None = Field(default=None, ge=0, le=20)
max_input_tokens: int | None = Field(default=None, ge=1, le=10_000_000)
max_tokens: int | None = Field(default=None, ge=1, le=1_000_000)
temperature: float | None = Field(default=None, ge=0, le=2)
stream_usage: bool | None = None
supports_thinking: bool = False
supports_reasoning_effort: bool = False
# DB-backed capability. Accepted here for stale clients, but never written
# into config.yaml; the dedicated capability endpoint is canonical.
supports_reasoning_effort: bool | None = None
supports_vision: bool = False
when_thinking_enabled: dict[str, Any] | None = None
when_thinking_disabled: dict[str, Any] | None = None
thinking: dict[str, Any] | None = None
use_responses_api: bool | None = None
output_version: str | None = Field(default=None, max_length=128)
# Optional on the wire so older administrator UIs preserve an existing
# bridge setting during edits. New models still resolve to ModelConfig's
# native default when the field is omitted.
write_file_transport: WriteFileTransport | None = None
extra_settings: dict[str, Any] = Field(default_factory=dict)
@field_validator("name", "use", "model")
@@ -148,6 +166,10 @@ class ModelTestRequest(BaseModel):
model: ModelUpsertRequest
class ReasoningEffortCapabilityRequest(BaseModel):
supports_reasoning_effort: bool
class ModelOrderRequest(BaseModel):
"""The complete ordered set of model stable names."""
@@ -167,13 +189,13 @@ def _mask_env_source(value: Any) -> str | None:
return None
def _to_admin_item(raw: dict[str, Any]) -> ModelAdminItem:
def _to_admin_item(
raw: dict[str, Any],
*,
supports_reasoning_effort: bool = False,
) -> ModelAdminItem:
api_key = raw.get("api_key")
extra = {
key: copy.deepcopy(value)
for key, value in raw.items()
if key not in _PRESERVED_FIELDS
}
extra = {key: copy.deepcopy(value) for key, value in raw.items() if key not in _PRESERVED_FIELDS}
return ModelAdminItem(
name=str(raw.get("name") or ""),
display_name=raw.get("display_name"),
@@ -183,17 +205,19 @@ def _to_admin_item(raw: dict[str, Any]) -> ModelAdminItem:
base_url=raw.get("base_url"),
request_timeout=raw.get("request_timeout"),
max_retries=raw.get("max_retries"),
max_input_tokens=raw.get("max_input_tokens"),
max_tokens=raw.get("max_tokens"),
temperature=raw.get("temperature"),
stream_usage=raw.get("stream_usage"),
supports_thinking=bool(raw.get("supports_thinking", False)),
supports_reasoning_effort=bool(raw.get("supports_reasoning_effort", False)),
supports_reasoning_effort=bool(supports_reasoning_effort),
supports_vision=bool(raw.get("supports_vision", False)),
when_thinking_enabled=copy.deepcopy(raw.get("when_thinking_enabled")),
when_thinking_disabled=copy.deepcopy(raw.get("when_thinking_disabled")),
thinking=copy.deepcopy(raw.get("thinking")),
use_responses_api=raw.get("use_responses_api"),
output_version=raw.get("output_version"),
write_file_transport=raw.get("write_file_transport", WriteFileTransport.NATIVE),
extra_settings=extra,
api_key_configured=bool(api_key),
api_key_source=_mask_env_source(api_key),
@@ -204,6 +228,55 @@ def _resolve_config_path() -> Path:
return AppConfig.resolve_config_path()
def _get_capability_store(request: Request, *, required: bool = True) -> ModelCapabilityStore | None:
app = getattr(request, "app", None)
store = getattr(getattr(app, "state", None), "model_capability_store", None)
if store is None and required:
raise HTTPException(status_code=503, detail="Model capability store not available")
return store
async def _capabilities_by_name(request: Request) -> dict[str, bool]:
store = _get_capability_store(request, required=False)
if store is None:
return {}
rows = await store.list_capabilities()
return {str(row.get("model_name") or ""): bool(row.get("supports_reasoning_effort", False)) for row in rows if row.get("model_name")}
def _admin_user_id(user: Any) -> str | None:
value = getattr(user, "id", None)
return str(value) if value is not None else None
def _validate_reasoning_capability(model: dict[str, Any], enabled: bool) -> None:
if enabled and not bool(model.get("supports_thinking", False)):
raise HTTPException(
status_code=422,
detail="Reasoning-effort selection requires a model that supports thinking",
)
async def _restore_capability(
store: ModelCapabilityStore,
model_name: str,
previous: dict[str, Any] | None,
) -> None:
"""Best-effort semantic rollback for a failed cross-store model update."""
try:
if previous is None:
await store.delete_capability(model_name)
return
await store.set_reasoning_effort_support(
model_name,
supports_reasoning_effort=bool(previous.get("supports_reasoning_effort", False)),
updated_by=previous.get("updated_by"),
)
except Exception:
logger.exception("Failed to roll back model capability for %s", model_name)
def _read_config_data(path: Path) -> tuple[str, dict[str, Any], list[dict[str, Any]]]:
raw_text = path.read_text(encoding="utf-8")
try:
@@ -246,17 +319,13 @@ def _replace_models_block(raw_text: str, models: list[dict[str, Any]]) -> str:
next_key = _TOP_LEVEL_KEY_RE.search(raw_text, block_match.end())
end = next_key.start() if next_key else len(raw_text)
previous_section = raw_text[block_match.end() : end]
preserved_comments = "".join(
line
for line in previous_section.splitlines(keepends=True)
if line.lstrip().startswith("#")
)
preserved_comments = "".join(line for line in previous_section.splitlines(keepends=True) if line.lstrip().startswith("#"))
rendered = _render_models_block(models, newline)
if preserved_comments:
if not preserved_comments.endswith(("\n", "\r")):
preserved_comments = f"{preserved_comments}{newline}"
rendered = f"{rendered}{preserved_comments}"
return f"{raw_text[:block_match.start()]}{rendered}{raw_text[end:]}"
return f"{raw_text[: block_match.start()]}{rendered}{raw_text[end:]}"
def _backup_and_write_config(path: Path, raw_before: str, raw_after: str) -> Path:
@@ -295,7 +364,13 @@ def _restore_backup(path: Path, backup_path: Path) -> None:
def _request_to_raw_model(payload: ModelUpsertRequest, existing: dict[str, Any] | None = None) -> dict[str, Any]:
merged = copy.deepcopy(existing or {})
supplied = payload.model_dump(exclude={"extra_settings", "clear_api_key"}, exclude_none=True)
supplied = payload.model_dump(
exclude={"extra_settings", "clear_api_key", "supports_reasoning_effort"},
exclude_none=True,
)
transport = supplied.get("write_file_transport")
if isinstance(transport, WriteFileTransport):
supplied["write_file_transport"] = transport.value
merged.update(supplied)
for key, value in payload.extra_settings.items():
normalized = str(key).strip()
@@ -309,6 +384,10 @@ def _request_to_raw_model(payload: ModelUpsertRequest, existing: dict[str, Any]
elif payload.api_key is None and existing is not None and "api_key" in existing:
merged["api_key"] = existing["api_key"]
# This capability is database-owned. Strip legacy YAML values whenever a
# model is rewritten so a later reload cannot silently regain authority.
merged.pop("supports_reasoning_effort", None)
# Validate the raw schema without resolving `$ENV_VAR` values. Environment
# resolution happens during the post-write runtime reload and is rolled back
# if unavailable.
@@ -327,7 +406,7 @@ def _redact_text(value: str, secrets: list[str]) -> str:
return result[:800]
async def _require_admin(request: Request) -> None:
async def _require_admin(request: Request):
user = getattr(request.state, "user", None)
if user is None:
user = await get_optional_user_from_request(request)
@@ -335,10 +414,23 @@ async def _require_admin(request: Request) -> None:
raise HTTPException(status_code=401, detail="Authentication is required")
if getattr(user, "system_role", None) != "admin":
raise HTTPException(status_code=403, detail="Model configuration requires an administrator")
return user
def _strip_database_owned_fields(models: list[dict[str, Any]]) -> list[dict[str, Any]]:
"""Remove legacy DB-owned capability keys from every rendered YAML row."""
sanitized: list[dict[str, Any]] = []
for item in models:
clean = copy.deepcopy(item)
clean.pop("supports_reasoning_effort", None)
sanitized.append(clean)
return sanitized
async def _save_models(request: Request, raw_before: str, models: list[dict[str, Any]]) -> list[dict[str, Any]]:
path = _resolve_config_path()
models = _strip_database_owned_fields(models)
raw_after = _replace_models_block(raw_before, models)
backup_path = await asyncio.to_thread(_backup_and_write_config, path, raw_before, raw_after)
try:
@@ -362,10 +454,19 @@ async def _save_models(request: Request, raw_before: str, models: list[dict[str,
async def list_model_configurations(request: Request) -> ModelAdminListResponse:
await _require_admin(request)
path = _resolve_config_path()
_, _, models = await asyncio.to_thread(_read_config_data, path)
(_, _, models), capabilities = await asyncio.gather(
asyncio.to_thread(_read_config_data, path),
_capabilities_by_name(request),
)
updated_at = datetime.fromtimestamp(path.stat().st_mtime, tz=UTC).isoformat()
return ModelAdminListResponse(
models=[_to_admin_item(item) for item in models],
models=[
_to_admin_item(
item,
supports_reasoning_effort=capabilities.get(str(item.get("name") or ""), False),
)
for item in models
],
config_path=str(path),
updated_at=updated_at,
)
@@ -373,15 +474,34 @@ async def list_model_configurations(request: Request) -> ModelAdminListResponse:
@router.post("", response_model=ModelAdminItem, status_code=201)
async def create_model_configuration(body: ModelUpsertRequest, request: Request) -> ModelAdminItem:
await _require_admin(request)
admin = await _require_admin(request)
async with _MUTATION_LOCK:
path = _resolve_config_path()
raw_before, _, models = await asyncio.to_thread(_read_config_data, path)
if any(str(item.get("name")) == body.name for item in models):
raise HTTPException(status_code=409, detail=f"A model named '{body.name}' already exists")
created = _request_to_raw_model(body)
await _save_models(request, raw_before, [*models, created])
return _to_admin_item(created)
capability_changed = "supports_reasoning_effort" in body.model_fields_set and body.supports_reasoning_effort is not None
capability_store = _get_capability_store(request, required=capability_changed)
previous_capability = None
if capability_changed and capability_store is not None:
_validate_reasoning_capability(created, bool(body.supports_reasoning_effort))
previous_capability = await capability_store.get_capability(body.name)
await capability_store.set_reasoning_effort_support(
body.name,
supports_reasoning_effort=bool(body.supports_reasoning_effort),
updated_by=_admin_user_id(admin),
)
try:
await _save_models(request, raw_before, [*models, created])
except Exception:
if capability_changed and capability_store is not None:
await _restore_capability(capability_store, body.name, previous_capability)
raise
return _to_admin_item(
created,
supports_reasoning_effort=bool(body.supports_reasoning_effort) if capability_changed else False,
)
@router.put("/order", response_model=list[ModelAdminItem])
@@ -411,12 +531,51 @@ async def reorder_model_configurations(body: ModelOrderRequest, request: Request
ordered_models = [models_by_name[name] for name in body.names]
await _save_models(request, raw_before, ordered_models)
return [_to_admin_item(item) for item in ordered_models]
capabilities = await _capabilities_by_name(request)
return [
_to_admin_item(
item,
supports_reasoning_effort=capabilities.get(str(item.get("name") or ""), False),
)
for item in ordered_models
]
@router.put(
"/capabilities/reasoning-effort/{model_name:path}",
response_model=ModelAdminItem,
)
async def update_reasoning_effort_capability(
model_name: str,
body: ReasoningEffortCapabilityRequest,
request: Request,
) -> ModelAdminItem:
"""Persist the per-model reasoning-effort selector capability in SQL."""
admin = await _require_admin(request)
async with _MUTATION_LOCK:
path = _resolve_config_path()
_, _, models = await asyncio.to_thread(_read_config_data, path)
model = next((item for item in models if str(item.get("name")) == model_name), None)
if model is None:
raise HTTPException(status_code=404, detail=f"Model '{model_name}' was not found")
_validate_reasoning_capability(model, body.supports_reasoning_effort)
store = _get_capability_store(request)
assert store is not None
await store.set_reasoning_effort_support(
model_name,
supports_reasoning_effort=body.supports_reasoning_effort,
updated_by=_admin_user_id(admin),
)
return _to_admin_item(
model,
supports_reasoning_effort=body.supports_reasoning_effort,
)
@router.put("/{model_name:path}", response_model=ModelAdminItem)
async def update_model_configuration(model_name: str, body: ModelUpsertRequest, request: Request) -> ModelAdminItem:
await _require_admin(request)
admin = await _require_admin(request)
if body.name != model_name:
raise HTTPException(status_code=422, detail="A model's stable name cannot be changed; edit its display name instead")
async with _MUTATION_LOCK:
@@ -426,10 +585,38 @@ async def update_model_configuration(model_name: str, body: ModelUpsertRequest,
if index is None:
raise HTTPException(status_code=404, detail=f"Model '{model_name}' was not found")
updated = _request_to_raw_model(body, models[index])
capability_explicit = "supports_reasoning_effort" in body.model_fields_set and body.supports_reasoning_effort is not None
capability_store = _get_capability_store(request, required=capability_explicit)
previous_capability = await capability_store.get_capability(model_name) if capability_store is not None else None
auto_disable_capability = bool(capability_store is not None and not bool(updated.get("supports_thinking", False)) and previous_capability and previous_capability.get("supports_reasoning_effort", False))
capability_changed = capability_explicit or auto_disable_capability
desired_capability = bool(body.supports_reasoning_effort) if capability_explicit else False
if capability_changed and capability_store is not None:
_validate_reasoning_capability(updated, desired_capability)
await capability_store.set_reasoning_effort_support(
model_name,
supports_reasoning_effort=desired_capability,
updated_by=_admin_user_id(admin),
)
next_models = [*models]
next_models[index] = updated
await _save_models(request, raw_before, next_models)
return _to_admin_item(updated)
try:
await _save_models(request, raw_before, next_models)
except Exception:
if capability_changed and capability_store is not None:
await _restore_capability(capability_store, model_name, previous_capability)
raise
if capability_changed:
supports_reasoning_effort = desired_capability
elif capability_store is not None:
current_capability = await capability_store.get_capability(model_name)
supports_reasoning_effort = bool(current_capability and current_capability.get("supports_reasoning_effort", False))
else:
supports_reasoning_effort = False
return _to_admin_item(
updated,
supports_reasoning_effort=supports_reasoning_effort,
)
@router.delete("/{model_name:path}", status_code=204)
@@ -443,7 +630,16 @@ async def delete_model_configuration(model_name: str, request: Request) -> None:
index = next((i for i, item in enumerate(models) if str(item.get("name")) == model_name), None)
if index is None:
raise HTTPException(status_code=404, detail=f"Model '{model_name}' was not found")
await _save_models(request, raw_before, [*models[:index], *models[index + 1 :]])
capability_store = _get_capability_store(request, required=False)
previous_capability = await capability_store.get_capability(model_name) if capability_store is not None else None
if capability_store is not None:
await capability_store.delete_capability(model_name)
try:
await _save_models(request, raw_before, [*models[:index], *models[index + 1 :]])
except Exception:
if capability_store is not None:
await _restore_capability(capability_store, model_name, previous_capability)
raise
@router.post("/test", response_model=ModelTestResponse)