ツール定義

ツールは通常のPython関数として定義し、act()呼び出しでモデルに渡すことができます。また、言語モデルに渡される名前と説明を制御するために、lmstudio.ToolFunctionDefを使用してツールを定義することも可能です。

ツールの構造

関数をツールとして定義するには、以下のいずれかの例に従ってください（最初の方法は通常、最も便利です）。

# Type hinted functions with clear names and docstrings
# may be used directly as tool definitions
def add(a: int, b: int) → int:
    """Given two numbers a and b, returns the sum of them."""
    # The SDK ensures arguments are coerced to their specified types
    return a + b

# Pass `add` directly to `act()` as a tool definition

重要: ツール名、説明、およびパラメータ定義はすべてモデルに渡されます！

これは、あなたの言葉遣いが生成の品質に影響を与えることを意味します。モデルがツールの使い方を理解できるように、常にツールの明確な説明を提供してください。

外部効果を持つツール（コンピュータの使用やAPI呼び出しなど）

ツールは、ファイルの作成、プログラムの呼び出し、さらにはAPIの呼び出しといった外部効果を持つこともできます。外部効果を持つツールを実装することで、LLMを実質的にローカルマシンでタスクを実行できる自律エージェントに変えることができます。

例: `create_file_tool`

create_file_tool.py

from pathlib import Path

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."

`create_file`ツールを使用するコード例:

example.py

import lmstudio as lms
from create_file_tool import create_file

model = lms.llm("qwen2.5-7b-instruct")
model.act(
  "Please create a file named output.txt with your understanding of the meaning of life.",
  [create_file],
)

ツール呼び出しエラーの処理

デフォルトでは、Python SDKのバージョン1.3.0以降は、ツール呼び出しによって発生した例外を自動的にテキストに変換し、言語モデルに報告します。多くの場合、このようにエラーが通知された際、言語モデルはリクエストを調整して失敗を回避するか、あるいは失敗をリクエストに対する有効な応答として受け入れることができます（例えば、提供されたツールを使って1を0で割ってみてください。結果を説明してください。のようなプロンプトを考えてみてください。この場合、期待される応答は、Pythonインタープリタがゼロ除算を指示されたときに発生させるZeroDivisionError例外の説明です）。

このエラー処理の挙動は、handle_invalid_tool_requestコールバックを使用してオーバーライドできます。例えば、次のコードはエラー処理を、クライアント内でローカルに例外を発生させる元の動作に戻します。

example.py

import lmstudio as lms

def divide(numerator: float, denominator: float) → float:
    """Divide the given numerator by the given denominator. Return the result."""
    return numerator / denominator

model = lms.llm("qwen2.5-7b-instruct")
chat = Chat()
chat.add_user_message(
    "Attempt to divide 1 by 0 using the tool. Explain the result."
)

def _raise_exc_in_client(
    exc: LMStudioPredictionError, request: ToolCallRequest | None
) → None:
    raise exc

act_result = llm.act(
    chat,
    [divide],
    handle_invalid_tool_request=_raise_exc_in_client,
)

ツールリクエストが渡された場合、コールバックの結果は次のように処理されます。

None: 元の例外テキストが変更されずにLLMに渡されます。
文字列: 返された文字列が、元の例外テキストの代わりにLLMに渡されます。
例外を発生させる（渡された例外か新しい例外かに関わらず）：発生した例外はクライアント内でローカルに伝播され、予測プロセスが終了します。

ツールリクエストが渡されない場合、コールバックの呼び出しは通知のみであり、例外をテキストに変換してLLMに渡すことはできません（ただし、別の例外に置き換えることは可能です）。これらのケースは、サーバーAPIとの期待される通信における失敗を示しており、予測プロセスが合理的に続行できないことを意味します。そのため、コールバックが例外を発生させない場合、呼び出し元コードは元の例外を直接発生させます。

ツール定義

ツールの構造

外部効果を持つツール（コンピュータの使用やAPI呼び出しなど）

例: create_file_tool