305 lines
13 KiB
Python
305 lines
13 KiB
Python
"""
|
||
app/services/tool_calling.py - OpenAI-compatible tool calling adapter.
|
||
|
||
This module bridges plain-text web model responses and OpenAI tool-calling
|
||
responses by:
|
||
- normalizing incoming `tools` / legacy `functions`
|
||
- converting tool history into plain-text prompts the web model can follow
|
||
- parsing structured JSON (and simple XML-like fallbacks) back into tool_calls
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from typing import Any, Dict, List, Optional
|
||
|
||
from app.services.tool_calling_common import (
|
||
AsyncToolRoundExecutor,
|
||
ToolRoundExecutor,
|
||
get_tool_calling_allow_media_postprocess,
|
||
get_tool_calling_sanitize_assistant_content_enabled,
|
||
logger,
|
||
)
|
||
from app.services.tool_calling_parse import (
|
||
_decode_tool_arguments,
|
||
build_tool_completion_response,
|
||
decode_browser_non_stream_payload,
|
||
extract_tool_calling_assistant_content,
|
||
iter_tool_stream_chunks,
|
||
parse_tool_response,
|
||
)
|
||
from app.services.tool_calling_prompts import (
|
||
build_browser_messages_for_tools,
|
||
has_tool_calling_request,
|
||
normalize_tool_request,
|
||
summarize_messages_for_debug,
|
||
)
|
||
from app.services.tool_calling_validation_retry import (
|
||
_build_focused_tool_retry_messages,
|
||
_build_partial_tool_success_response,
|
||
_build_tool_calling_degraded_response,
|
||
_build_tool_retry_messages,
|
||
_describe_tool_retry_strategy,
|
||
_get_tool_failure_degrade_enabled,
|
||
_get_tool_retry_strategy,
|
||
_get_tool_validation_retry_limit,
|
||
_has_non_retryable_tool_errors,
|
||
_inspect_tool_response,
|
||
_is_partial_tool_success_eligible,
|
||
_summarize_tool_response_errors,
|
||
)
|
||
|
||
|
||
def _copy_message_list_shallow(messages: Optional[List[Dict[str, Any]]]) -> List[Dict[str, Any]]:
|
||
return [dict(msg) if isinstance(msg, dict) else msg for msg in (messages or [])]
|
||
|
||
|
||
def complete_tool_calling_roundtrip(
|
||
messages: List[Dict[str, Any]],
|
||
tools: List[Dict[str, Any]],
|
||
tool_choice: Any,
|
||
parallel_tool_calls: Optional[bool],
|
||
round_executor: ToolRoundExecutor,
|
||
stop_checker=None,
|
||
) -> Dict[str, Any]:
|
||
conversation = _copy_message_list_shallow(messages)
|
||
retry_limit = _get_tool_validation_retry_limit()
|
||
retry_strategy = _get_tool_retry_strategy()
|
||
total_attempts = retry_limit + 1
|
||
last_summary = "tool_call_validation_failed"
|
||
last_parsed: Dict[str, Any] = {"mode": "final", "content": "", "tool_calls": []}
|
||
pending_retry_messages: Optional[List[Dict[str, str]]] = None
|
||
|
||
for attempt in range(1, total_attempts + 1):
|
||
if stop_checker and stop_checker():
|
||
raise RuntimeError("tool_calling_cancelled")
|
||
|
||
if pending_retry_messages is not None:
|
||
browser_messages = pending_retry_messages
|
||
else:
|
||
browser_messages = build_browser_messages_for_tools(
|
||
messages=conversation,
|
||
tools=tools,
|
||
tool_choice=tool_choice,
|
||
parallel_tool_calls=parallel_tool_calls,
|
||
)
|
||
assistant_text = str(round_executor(browser_messages) or "")
|
||
parsed = parse_tool_response(assistant_text, tools)
|
||
last_parsed = parsed
|
||
inspection = _inspect_tool_response(
|
||
raw_text=assistant_text,
|
||
parsed=parsed,
|
||
tools=tools,
|
||
tool_choice=tool_choice,
|
||
parallel_tool_calls=parallel_tool_calls,
|
||
)
|
||
errors = inspection.get("errors") or []
|
||
if not errors:
|
||
if attempt > 1:
|
||
logger.warning(
|
||
"[tool_calling] 函数调用候选已在内部修复后通过校验 "
|
||
f"轮次={attempt}/{total_attempts} "
|
||
f"已用修复重试={attempt - 1}/{retry_limit} "
|
||
f"策略={_describe_tool_retry_strategy(retry_strategy)}"
|
||
)
|
||
return parsed
|
||
|
||
last_summary = _summarize_tool_response_errors(errors)
|
||
# 修复(2a):请求侧确定性错误(如客户端 tools schema 非法,invalid_request)
|
||
# 模型重试也不可能通过,直接按“无剩余重试”处理,不再烧掉重试轮次。
|
||
non_retryable = _has_non_retryable_tool_errors(errors)
|
||
if non_retryable or attempt >= total_attempts:
|
||
# 修复(1):部分成功只在重试额度耗尽(或确定不可重试)后才启用,
|
||
# 避免第一轮出现 ≥1 通过 + ≥1 被拒时就提前返回子集、静默丢弃失败的调用。
|
||
if _is_partial_tool_success_eligible(inspection, parallel_tool_calls):
|
||
return _build_partial_tool_success_response(parsed, inspection)
|
||
if non_retryable:
|
||
logger.warning(
|
||
"[tool_calling] 检测到请求侧确定性错误(invalid_request),停止内部修复重试 "
|
||
f"轮次={attempt}/{total_attempts} "
|
||
f"最后错误={last_summary}"
|
||
)
|
||
else:
|
||
logger.warning(
|
||
"[tool_calling] 函数调用内部修复次数已耗尽 "
|
||
f"轮次={attempt}/{total_attempts} "
|
||
f"配置上限={retry_limit} "
|
||
f"策略={_describe_tool_retry_strategy(retry_strategy)} "
|
||
f"最后错误={last_summary}"
|
||
)
|
||
if _get_tool_failure_degrade_enabled():
|
||
logger.warning("[tool_calling] 修复耗尽,尝试保留原始 tool_calls;不会降级为普通文本")
|
||
return _build_tool_calling_degraded_response(last_parsed, inspection, last_summary)
|
||
raise RuntimeError(f"tool_call_validation_exhausted: {last_summary}")
|
||
|
||
remaining_retries = total_attempts - attempt
|
||
logger.warning(
|
||
"[tool_calling] 函数调用候选校验未通过,准备进行内部修复重试 "
|
||
f"轮次={attempt}/{total_attempts} "
|
||
f"配置上限={retry_limit} "
|
||
f"策略={_describe_tool_retry_strategy(retry_strategy)} "
|
||
f"剩余重试={remaining_retries} "
|
||
f"原因={last_summary}"
|
||
)
|
||
if retry_strategy == "focused_repair":
|
||
pending_retry_messages = _build_focused_tool_retry_messages(
|
||
original_messages=messages,
|
||
tools=tools,
|
||
tool_choice=tool_choice,
|
||
parallel_tool_calls=parallel_tool_calls,
|
||
raw_text=assistant_text,
|
||
parsed=parsed,
|
||
errors=errors,
|
||
attempt=attempt,
|
||
total_attempts=total_attempts,
|
||
)
|
||
else:
|
||
conversation.extend(
|
||
_build_tool_retry_messages(
|
||
raw_text=assistant_text,
|
||
parsed=parsed,
|
||
errors=errors,
|
||
attempt=attempt,
|
||
total_attempts=total_attempts,
|
||
)
|
||
)
|
||
pending_retry_messages = None
|
||
|
||
if _get_tool_failure_degrade_enabled():
|
||
logger.warning("[tool_calling] 修复耗尽,尝试保留原始 tool_calls;不会降级为普通文本")
|
||
return _build_tool_calling_degraded_response(last_parsed, None, last_summary)
|
||
raise RuntimeError(f"tool_call_validation_exhausted: {last_summary}")
|
||
|
||
|
||
async def complete_tool_calling_roundtrip_async(
|
||
messages: List[Dict[str, Any]],
|
||
tools: List[Dict[str, Any]],
|
||
tool_choice: Any,
|
||
parallel_tool_calls: Optional[bool],
|
||
round_executor: AsyncToolRoundExecutor,
|
||
stop_checker=None,
|
||
) -> Dict[str, Any]:
|
||
conversation = _copy_message_list_shallow(messages)
|
||
retry_limit = _get_tool_validation_retry_limit()
|
||
retry_strategy = _get_tool_retry_strategy()
|
||
total_attempts = retry_limit + 1
|
||
last_summary = "tool_call_validation_failed"
|
||
last_parsed: Dict[str, Any] = {"mode": "final", "content": "", "tool_calls": []}
|
||
pending_retry_messages: Optional[List[Dict[str, str]]] = None
|
||
|
||
for attempt in range(1, total_attempts + 1):
|
||
if stop_checker and stop_checker():
|
||
raise RuntimeError("tool_calling_cancelled")
|
||
|
||
if pending_retry_messages is not None:
|
||
browser_messages = pending_retry_messages
|
||
else:
|
||
browser_messages = build_browser_messages_for_tools(
|
||
messages=conversation,
|
||
tools=tools,
|
||
tool_choice=tool_choice,
|
||
parallel_tool_calls=parallel_tool_calls,
|
||
)
|
||
assistant_text = str(await round_executor(browser_messages) or "")
|
||
parsed = parse_tool_response(assistant_text, tools)
|
||
last_parsed = parsed
|
||
inspection = _inspect_tool_response(
|
||
raw_text=assistant_text,
|
||
parsed=parsed,
|
||
tools=tools,
|
||
tool_choice=tool_choice,
|
||
parallel_tool_calls=parallel_tool_calls,
|
||
)
|
||
errors = inspection.get("errors") or []
|
||
if not errors:
|
||
if attempt > 1:
|
||
logger.warning(
|
||
"[tool_calling] 函数调用候选已在内部修复后通过校验 "
|
||
f"轮次={attempt}/{total_attempts} "
|
||
f"已用修复重试={attempt - 1}/{retry_limit} "
|
||
f"策略={_describe_tool_retry_strategy(retry_strategy)}"
|
||
)
|
||
return parsed
|
||
|
||
last_summary = _summarize_tool_response_errors(errors)
|
||
# 修复(2a):请求侧确定性错误(如客户端 tools schema 非法,invalid_request)
|
||
# 模型重试也不可能通过,直接按“无剩余重试”处理,不再烧掉重试轮次。
|
||
non_retryable = _has_non_retryable_tool_errors(errors)
|
||
if non_retryable or attempt >= total_attempts:
|
||
# 修复(1):部分成功只在重试额度耗尽(或确定不可重试)后才启用,
|
||
# 避免第一轮出现 ≥1 通过 + ≥1 被拒时就提前返回子集、静默丢弃失败的调用。
|
||
if _is_partial_tool_success_eligible(inspection, parallel_tool_calls):
|
||
return _build_partial_tool_success_response(parsed, inspection)
|
||
if non_retryable:
|
||
logger.warning(
|
||
"[tool_calling] 检测到请求侧确定性错误(invalid_request),停止内部修复重试 "
|
||
f"轮次={attempt}/{total_attempts} "
|
||
f"最后错误={last_summary}"
|
||
)
|
||
else:
|
||
logger.warning(
|
||
"[tool_calling] 函数调用内部修复次数已耗尽 "
|
||
f"轮次={attempt}/{total_attempts} "
|
||
f"配置上限={retry_limit} "
|
||
f"策略={_describe_tool_retry_strategy(retry_strategy)} "
|
||
f"最后错误={last_summary}"
|
||
)
|
||
if _get_tool_failure_degrade_enabled():
|
||
logger.warning("[tool_calling] 修复耗尽,尝试保留原始 tool_calls;不会降级为普通文本")
|
||
return _build_tool_calling_degraded_response(last_parsed, inspection, last_summary)
|
||
raise RuntimeError(f"tool_call_validation_exhausted: {last_summary}")
|
||
|
||
remaining_retries = total_attempts - attempt
|
||
logger.warning(
|
||
"[tool_calling] 函数调用候选校验未通过,准备进行内部修复重试 "
|
||
f"轮次={attempt}/{total_attempts} "
|
||
f"配置上限={retry_limit} "
|
||
f"策略={_describe_tool_retry_strategy(retry_strategy)} "
|
||
f"剩余重试={remaining_retries} "
|
||
f"原因={last_summary}"
|
||
)
|
||
if retry_strategy == "focused_repair":
|
||
pending_retry_messages = _build_focused_tool_retry_messages(
|
||
original_messages=messages,
|
||
tools=tools,
|
||
tool_choice=tool_choice,
|
||
parallel_tool_calls=parallel_tool_calls,
|
||
raw_text=assistant_text,
|
||
parsed=parsed,
|
||
errors=errors,
|
||
attempt=attempt,
|
||
total_attempts=total_attempts,
|
||
)
|
||
else:
|
||
conversation.extend(
|
||
_build_tool_retry_messages(
|
||
raw_text=assistant_text,
|
||
parsed=parsed,
|
||
errors=errors,
|
||
attempt=attempt,
|
||
total_attempts=total_attempts,
|
||
)
|
||
)
|
||
pending_retry_messages = None
|
||
|
||
if _get_tool_failure_degrade_enabled():
|
||
logger.warning("[tool_calling] 修复耗尽,尝试保留原始 tool_calls;不会降级为普通文本")
|
||
return _build_tool_calling_degraded_response(last_parsed, None, last_summary)
|
||
raise RuntimeError(f"tool_call_validation_exhausted: {last_summary}")
|
||
|
||
__all__ = [
|
||
"build_browser_messages_for_tools",
|
||
"build_tool_completion_response",
|
||
"extract_tool_calling_assistant_content",
|
||
"get_tool_calling_allow_media_postprocess",
|
||
"get_tool_calling_sanitize_assistant_content_enabled",
|
||
"decode_browser_non_stream_payload",
|
||
"complete_tool_calling_roundtrip",
|
||
"complete_tool_calling_roundtrip_async",
|
||
"has_tool_calling_request",
|
||
"iter_tool_stream_chunks",
|
||
"normalize_tool_request",
|
||
"parse_tool_response",
|
||
"summarize_messages_for_debug",
|
||
"_decode_tool_arguments",
|
||
]
|