.act() 调用

如何使用 .act() 调用将大语言模型（LLM）转变为可以在本地机器上执行任务的自主智能体。

自动工具调用

我们引入了执行“回合”的概念，来描述运行工具、将其输出提供给 LLM，然后等待 LLM 决定下一步该做什么的组合过程。

执行回合

 • run a tool ->
 ↑   • provide the result to the LLM ->
 │       • wait for the LLM to generate a response
 │
 └────────────────────────────────────────┘ └➔ (return)

模型可能会选择多次运行工具，然后才返回最终结果。例如，如果 LLM 正在编写代码，它可能会选择编译或运行程序，修复错误，然后再次运行，反复执行直到获得所需的结果。

基于此，我们说 .act() API 是一个自动的“多轮”工具调用 API。

快速示例

import lmstudio as lms

def multiply(a: float, b: float) -> float:
    """Given two numbers a and b. Returns the product of them."""
    return a * b

model = lms.llm("qwen2.5-7b-instruct")
model.act(
  "What is the result of 12345 multiplied by 54321?",
  [multiply],
  on_message=print,
)

大语言模型（LLM）“使用工具”意味着什么？

LLM 大多是文本输入、文本输出的程序。所以，您可能会问“LLM 如何使用工具？”答案是，一些 LLM 经过训练，会要求人类为它们调用工具，并期望工具输出以某种格式返回。

想象一下你正在通过电话为某人提供电脑支持。你可能会说“帮我运行这个命令……好，它输出了什么？……好，现在点击那里然后告诉我会显示什么……”。在这种情况下，你就是那个大语言模型（LLM）！而你正在通过电话另一端的人间接地“调用工具”。

并行运行多个工具调用

默认情况下，Python SDK 1.4.0 及更高版本一次只会运行一个工具调用请求，即使模型在单个响应消息中请求了多个工具调用也是如此。这确保了即使工具实现不支持多个并发调用，请求也能被正确处理。

当已知工具实现是线程安全的，且足够慢且频繁、值得并行运行时，max_parallel_tool_calls 选项可以指定在单个模型响应中并行处理的工具调用请求的最大数量。此值默认为 1（在开始下一个工具调用之前等待当前调用完成）。将此值设置为 None 将自动根据该进程可用的 CPU 核心数的倍数来扩展最大并行工具调用数量。

重要提示：模型选择

为工具使用选择的模型将极大影响性能。

选择模型时的一些通用指南

并非所有模型都具备智能工具调用的能力
越大越好（例如，7B 参数的模型通常比 3B 参数的模型表现更好）
我们观察到 Qwen2.5-7B-Instruct 在各种情况下都表现良好
此指南可能会发生变化

示例：多个工具

以下代码演示了如何在单个 .act() 调用中提供多个工具。

import math
import lmstudio as lms

def add(a: int, b: int) -> int:
    """Given two numbers a and b, returns the sum of them."""
    return a + b

def is_prime(n: int) -> bool:
    """Given a number n, returns True if n is a prime number."""
    if n < 2:
        return False
    sqrt = int(math.sqrt(n))
    for i in range(2, sqrt):
        if n % i == 0:
            return False
    return True

model = lms.llm("qwen2.5-7b-instruct")
model.act(
  "Is the result of 12345 + 45668 a prime? Think step by step.",
  [add, is_prime],
  on_message=print,
)

示例：带有创建文件工具的聊天循环

以下代码使用一个可以创建文件的 LLM 智能体创建了一个对话循环。

import readline # Enables input line editing
from pathlib import Path

import lmstudio as lms

def create_file(name: str, content: str):
    """Create a file with the given name and content."""
    dest_path = Path(name)
    if dest_path.exists():
        return "Error: File already exists."
    try:
        dest_path.write_text(content, encoding="utf-8")
    except Exception as exc:
        return "Error: {exc!r}"
    return "File created."

def print_fragment(fragment, round_index=0):
    # .act() supplies the round index as the second parameter
    # Setting a default value means the callback is also
    # compatible with .complete() and .respond().
    print(fragment.content, end="", flush=True)

model = lms.llm()
chat = lms.Chat("You are a task focused AI assistant")

while True:
    try:
        user_input = input("You (leave blank to exit): ")
    except EOFError:
        print()
        break
    if not user_input:
        break
    chat.add_user_message(user_input)
    print("Bot: ", end="", flush=True)
    model.act(
        chat,
        [create_file],
        on_message=chat.append,
        on_prediction_fragment=print_fragment,
    )
    print()

进度回调

与使用工具的智能体进行的复杂交互可能需要一些时间来处理。

任何预测请求的常规进度回调都是可用的，但其预期功能与单轮预测的功能不同。

on_prompt_processing_progress：在每轮预测的提示词处理期间调用。接收进度比例（浮点数）和轮次索引作为位置参数。
on_first_token：在每轮预测的提示词处理完成后调用。接收轮次索引作为其唯一参数。
on_prediction_fragment：在客户端收到每个预测片段时调用。接收预测片段和轮次索引作为位置参数。
on_message：在每轮预测完成时，携带助手响应消息进行调用；在每个工具调用请求完成时，携带工具结果消息进行调用。旨在将收到的消息追加到聊天历史记录实例中，因此该方法*不*接收轮次索引作为参数。

以下附加回调可用于监控预测轮次

on_round_start：在提交每轮预测请求之前调用。接收轮次索引作为其唯一参数。
on_prediction_completed：在当前轮次的预测已完成，但在启动任何请求的工具调用之前调用。接收该轮次的预测结果作为其唯一参数。一轮预测结果是一个带有附加 round_index 属性的常规预测结果。
on_round_end：在当前轮次的所有工具调用请求处理完毕后调用。

最后，当智能体发出无效的工具请求时，应用程序可以请求接收通知

handle_invalid_tool_request：在工具请求无法处理时调用。接收即将报告的异常，以及导致问题的原始工具请求。当没有提供工具请求时，这纯粹是在智能体交互引发给定异常之前发出的不可恢复错误的通知（允许应用程序引发其自己的异常作为替代）。当提供了工具请求时，它表示异常的文本描述将作为该失败工具请求的结果传回给智能体，而不是在本地引发。在这些情况下，回调可以返回 None 表示应将错误描述发送给智能体，或者在本地引发给定的异常（或不同的异常），或者返回应发送给智能体以代替错误描述的文本字符串。

有关定义工具的更多详细信息，以及覆盖无效工具请求处理以在本地引发所有异常（而不是将其传回智能体）的示例，请参阅工具定义。