5.5 · 工具调用与函数使用（Tool Calling and Function Use）

工具调用与函数使用

工具调用与函数使用

相关源文件

以下文件为本维基页面的生成提供了上下文：

• agent/canvas.py
• agent/component/agent_with_tools.py
• agent/component/base.py
• agent/component/categorize.py
• agent/component/llm.py
• agent/tools/base.py
• api/apps/llm_app.py
• common/mcp_tool_call_conn.py
• conf/llm_factories.json
• rag/llm/__init__.py
• rag/llm/chat_model.py
• rag/llm/cv_model.py
• rag/llm/embedding_model.py
• rag/llm/rerank_model.py
• rag/llm/sequence2txt_model.py
• rag/llm/tts_model.py
• rag/prompts/generator.py
• web/src/components/svg-icon.tsx
• web/src/constants/llm.ts
• web/src/pages/user-setting/setting-model/constant.ts
• web/src/utils/common-util.ts

本文档描述了 RAGFlow 的工具调用与函数调用系统，该系统使大语言模型（LLM）能够在聊天补全过程中动态调用外部函数。该机制允许大语言模型执行查询数据库、调用 API 或执行自定义逻辑等操作，作为对话工作流的一部分。

本文档涵盖了工具绑定机制、与 OpenAI 函数调用兼容的函数模式生成、多轮与流式工具执行、结果集成、错误韧性，以及 Agent 组件如何编排这些能力。

有关模型配置，请参阅 5.4 租户配置与模型管理。有关通用大语言模型抽象，请参阅 5.1 LLMBundle 与模型类型。

目的与范围

工具调用系统提供以下核心能力：

• 工具绑定：将外部函数模式与大语言模型绑定，并附带上下文会话，使大语言模型能够通过标准化的类 JSON-RPC 接口调用工具。
• 函数模式生成：为工具构建并注入 JSON Schema 定义，使大语言模型能够解析参数结构。
• 多轮执行：支持迭代过程，大语言模型调用工具、工具执行、结果反馈，然后大语言模型生成进一步调用或答案。
• 流式支持：支持大语言模型的流式响应，在执行函数调用前累积部分工具调用参数。
• 错误处理与韧性：包含 JSON 解析修复、重试逻辑、错误分类和回退机制。
• Agent 集成：通过外部 MCP 服务器和 Agent 内部工具组件实现高级工具编排。

模型对工具调用的支持

工具调用支持由模型配置中的布尔值 is_tools 属性标识。该标志在 Base 聊天模型类中管理，并在工具绑定时进行检查。

支持的模型配置

JSON 文件 conf/llm_factories.json 枚举了支持的模型，并为每个模型指定了 is_tools 标志。例如：

该标志决定了运行时是否为该模型激活工具调用 conf/llm_factories.json:3-150、rag/llm/chat_model.py:122-125。

核心架构

工具调用流程概述

工具调用能力将用户自然语言桥接到后端注册的可执行函数代码。系统管理函数模式、执行上下文和按需调用。

图表：工具调用组件映射

来源：api/db/services/llm_service.py:85-93、rag/llm/chat_model.py:270-280、rag/llm/chat_model.py:120-150

工具调用的数据结构

运行时，工具调用数据与 OpenAI 函数调用参数对齐：

工具模式使大语言模型能够理解预期的参数并相应地格式化调用。

工具绑定机制

绑定工具将可调用函数（工具实例）及其 JSON 模式与大语言模型实例关联起来。这使大语言模型能够生成系统执行的结构化函数调用。

在 LLMBundle 和聊天模型中的绑定

• LLMBundle.bind_tools(toolcall_session, tools) 将工具和工具会话附加到内部聊天模型实例；它通过 is_tools 检查模型是否支持工具调用 api/db/services/llm_service.py:89-93。

• ChatModel.Base.bind_tools(toolcall_session, tools) 将工具会话对象和工具列表存储在模型实例变量中，并断言它们已提供 rag/llm/chat_model.py:270-280。

智能体组件工具绑定

Agent 组件在更高级别集成工具绑定：

• 它加载工具组件（原生工具）和外部 MCP 服务器工具。
• 每个工具接收一个唯一的基于索引的函数名称，以避免冲突。
• 工具元数据被转换为 OpenAI 函数模式格式并聚合。
• 通过调用 bind_tools 将这些工具注册到 LLMBundle 的聊天模型 agent/component/agent_with_tools.py:73-114。

图表：工具绑定逻辑流程

来源：api/db/services/llm_service.py:89-93、rag/llm/chat_model.py:270-280、agent/component/agent_with_tools.py:73-114

多轮工具执行流程

当大语言模型生成工具调用请求时，系统执行请求的工具并将结果反馈回去。此过程循环进行，允许多次工具调用。

async_chat_with_tools 中的执行步骤

1. 初始大语言模型聊天：发送用户消息，附加系统提示，并请求可能包含工具调用的响应 rag/llm/chat_model.py:279-290。

1. 检测工具调用：检查响应是否包含指示工具函数调用的 tool_calls rag/llm/chat_model.py:297。

1. 解析参数：使用 json_repair.loads 稳健地解析可能格式错误的大语言模型 JSON 输出 rag/llm/chat_model.py:311。

1. 调用工具：通过 toolcall_session.tool_call() 使用参数异步调用请求的工具函数 rag/llm/chat_model.py:310-317。

1. 更新历史记录：将工具响应作为助手消息内容附加，角色为 "function"，并包含函数调用详情。

1. 重复或完成：使用更新后的消息重新运行聊天；循环直到达到 max_rounds 限制。完成后，返回最终文本和 Token 使用量 rag/llm/chat_model.py:320-331。

流式工具执行

流式响应使工具调用变得复杂，因为工具调用参数可能以增量片段（delta）形式到达。系统在执行工具前累积这些片段。

async_chat_streamly_with_tools 中的流式执行

• 从大语言模型流式接收块。

• 如果块包含即时用户内容，直接将其返回给调用者。

• 如果块包含部分工具调用参数（delta），则按工具调用 id 键累积它们。

• 当块指示完成（完成原因 function_call 或 stop）时，组装完整参数，向流返回一条详细消息，然后执行工具。

• 递归处理来自工具执行结果或大语言模型继续的进一步工具调用 rag/llm/chat_model.py:333-442。

图表：流式工具执行状态机

来源：rag/llm/chat_model.py:333-442

错误处理与韧性

• 错误分类：_classify_error() 方法将遇到的错误文本字符串映射到定义的错误代码（例如，速率限制、认证错误、无效请求）。此分类有助于重试或回退逻辑 rag/llm/chat_model.py:130-150。

• 重试策略：使用可配置的指数退避和随机抖动，以避免失败时紧密的重试循环。由 max_retries、max_rounds 和 base_delay 参数控制 rag/llm/chat_model.py:120-130。

• JSON 修复：由于大语言模型 JSON 输出不完美，使用 json_repair 稳健地解析工具调用参数，避免格式错误的 JSON 失败 rag/llm/chat_model.py:310-314。

• 模型特定策略：_apply_model_family_policies 按模型系列自定义生成配置，例如为 Qwen3 禁用"思考"或为 Kimi-k2.5 模型调整温度，以优化工具调用行为 rag/llm/chat_model.py:60-110。

• 最大轮次强制执行：如果超过 max_rounds，工具调用停止，系统添加一条通知，说明由于大语言模型上下文窗口限制，答案已被截断，然后生成最终答案，不再进行进一步工具调用 rag/llm/chat_model.py:320-325。

总结

RAGFlow 的工具调用功能为大语言模型驱动的聊天工作流提供了一种稳健、可扩展的机制，通过结构化函数调用外部工具。它支持多轮和流式交互、错误恢复以及 Agent 组件内的高级集成，从而实现复杂的、支持工具的 AI 代理。

附录

关键类与函数

交叉引用

• Agent 工具使用与 MCP 集成：请参阅 8.6 Agent 工具与 ReAct 循环
• 大语言模型抽象与模型类型：请参阅 5.1 LLMBundle 与模型类型
• 租户模型配置：请参阅 5.4 租户配置与模型管理

来源： rag/llm/chat_model.py:15-250、270-442 api/db/services/llm_service.py:85-95 conf/llm_factories.json:1-150 agent/component/agent_with_tools.py:70-115