Erstellen und Verwenden von Tool-Paketen#

In diesem Dokument führen wir Sie durch den Prozess der Entwicklung Ihres eigenen Tool-Pakets und geben Ihnen detaillierte Schritte und Ratschläge zur Nutzung Ihrer Kreation.

Das benutzerdefinierte Tool ist das von Ihnen selbst entwickelte Prompt Flow Tool. Wenn Sie es nützlich finden, können Sie dieser Anleitung folgen, um es zu einem Tool-Paket zu machen. Dies ermöglicht es Ihnen, es bequem wiederzuverwenden, es mit Ihrem Team zu teilen oder es an jeden auf der Welt zu verteilen.

Nach erfolgreicher Installation des Pakets wird Ihr benutzerdefiniertes "Tool" wie unten in der VSCode-Erweiterung angezeigt: custom-tool-list

Erstellen Sie Ihr eigenes Tool-Paket#

Ihr Tool-Paket sollte ein Python-Paket sein. Um es schnell auszuprobieren, verwenden Sie einfach my-tools-package 0.0.1 und überspringen Sie diesen Abschnitt.

Voraussetzungen#

Erstellen Sie eine neue Conda-Umgebung mit Python 3.9 oder 3.10. Führen Sie den folgenden Befehl aus, um PromptFlow-Abhängigkeiten zu installieren

pip install promptflow

Installieren Sie Pytest-Pakete zum Ausführen von Tests

pip install pytest pytest-mock

Klonen Sie das PromptFlow-Repository von GitHub mit dem folgenden Befehl

git clone https://github.com/microsoft/promptflow.git

Benutzerdefiniertes Tool-Paket erstellen#

Führen Sie den folgenden Befehl im Stammverzeichnis aus, um Ihr Tool-Projekt schnell zu erstellen

python <promptflow github repo>\scripts\tool\generate_tool_package_template.py --destination <your-tool-project> --package-name <your-package-name> --tool-name <your-tool-name> --function-name <your-tool-function-name>

Zum Beispiel

python D:\proj\github\promptflow\scripts\tool\generate_tool_package_template.py --destination hello-world-proj --package-name hello-world --tool-name hello_world_tool --function-name get_greeting_message

Dieses automatisch generierte Skript erstellt ein Tool für Sie. Die Parameter destination und package-name sind obligatorisch. Die Parameter tool-name und function-name sind optional. Wenn sie nicht ausgefüllt sind, wird tool-name standardmäßig auf hello_world_tool und function-name auf tool-name gesetzt.

Der Befehl generiert das Tool-Projekt wie folgt mit einem Tool hello_world_tool.py darin

hello-world-proj/    
│    
├── hello_world/    
│   ├── tools/    
│   │   ├── __init__.py    
│   │   ├── hello_world_tool.py    
│   │   └── utils.py    
│   ├── yamls/    
│   │   └── hello_world_tool.yaml    
│   └── __init__.py    
│    
├── tests/     
│   ├── __init__.py    
│   └── test_hello_world_tool.py    
│    
├── MANIFEST.in    
│    
└── setup.py  

Die nachstehend aufgeführten Punkte erläutern den Zweck jeder Ordner/Datei im Paket. Wenn Ihr Ziel ist, mehrere Tools innerhalb Ihres Pakets zu entwickeln, achten Sie bitte genau auf Punkt 2 und 5.

hello-world-proj: Dies ist das Quellverzeichnis. Der gesamte Quellcode Ihres Projekts sollte in diesem Verzeichnis platziert werden.
hello-world/tools: Dieses Verzeichnis enthält die einzelnen Tools für Ihr Projekt. Ihr Tool-Paket kann entweder ein Tool oder viele Tools enthalten. Wenn Sie ein neues Tool hinzufügen, sollten Sie eine weitere *_tool.py-Datei unter dem Ordner tools erstellen.
hello-world/tools/hello_world_tool.py: Entwickeln Sie Ihr Tool innerhalb der def-Funktion. Verwenden Sie den Dekorator @tool, um die Funktion als Tool zu identifizieren.

[!Hinweis] Es gibt zwei Möglichkeiten, ein Tool zu schreiben. Der Standardweg und der empfohlene Weg ist die Implementierung über Funktionen. Sie können auch die Implementierung über Klassen verwenden, siehe my_tool_2.py als Beispiel.
hello-world/tools/utils.py: Diese Datei implementiert die Methode zur Auflistung von Tools, die alle definierten Tools sammelt. Es ist erforderlich, diese Methode zur Auflistung von Tools zu haben, da sie es der Benutzeroberfläche (UI) ermöglicht, Ihre Tools abzurufen und in der UI anzuzeigen.

[!Hinweis] Sie müssen keine eigene Auflistungsfunktion erstellen, wenn Sie die vorhandene Ordnerstruktur beibehalten. Sie können einfach die automatisch generierte Auflistungsfunktion verwenden, die in der Datei utils.py bereitgestellt wird.
hello_world/yamls/hello_world_tool.yaml: Tool-YAMLs definieren die Metadaten des Tools. Die Methode zur Auflistung von Tools, wie in utils.py beschrieben, ruft diese Tool-YAMLs ab.

[!Hinweis] Wenn Sie ein neues Tool erstellen, vergessen Sie nicht, auch die entsprechende Tool-YAML zu erstellen. Sie können den folgenden Befehl unter Ihrem Tool-Projekt ausführen, um Ihre Tool-YAML automatisch zu generieren. Möglicherweise möchten Sie -n für name und -d für description angeben, die als Tool-Name und Tooltip in der Prompt Flow UI angezeigt werden.
```
python <promptflow github repo>\scripts\tool\generate_package_tool_meta.py -m <tool_module> -o <tool_yaml_path> -n <tool_name> -d <tool_description>
```
Zum Beispiel
```
python D:\proj\github\promptflow\scripts\tool\generate_package_tool_meta.py -m hello_world.tools.hello_world_tool -o hello_world\yamls\hello_world_tool.yaml -n "Hello World Tool" -d "This is my hello world tool."
```
Um Ihr Tool-Modul zu befüllen, halten Sie sich an das Muster <package_name>.tools.<tool_name>, was den Ordnerpfad zu Ihrem Tool innerhalb des Pakets darstellt.
tests: Dieses Verzeichnis enthält alle Ihre Tests, obwohl diese für die Erstellung Ihres benutzerdefinierten Tool-Pakets nicht erforderlich sind. Wenn Sie ein neues Tool hinzufügen, können Sie auch entsprechende Tests erstellen und diese in diesem Verzeichnis ablegen. Führen Sie den folgenden Befehl unter Ihrem Tool-Projekt aus
```
pytest tests
```
MANIFEST.in: Diese Datei wird verwendet, um festzustellen, welche Dateien in die Distribution des Projekts aufgenommen werden sollen. Tool-YAML-Dateien sollten in MANIFEST.in aufgenommen werden, damit Ihre Tool-YAMLs gepackt werden und Ihre Tools in der UI angezeigt werden können.

[!Hinweis] Sie müssen diese Datei nicht aktualisieren, wenn Sie die vorhandene Ordnerstruktur beibehalten.
setup.py: Diese Datei enthält Metadaten über Ihr Projekt wie Name, Version, Autor und mehr. Darüber hinaus wird der Einstiegspunkt automatisch für Sie im Skript generate_tool_package_template.py konfiguriert. In Python hilft die Konfiguration des Einstiegspunkts in setup.py dabei, den primären Ausführungspunkt für ein Paket festzulegen und seine Integration mit anderer Software zu vereinfachen.

Der Einstiegspunkt package_tools wird zusammen mit der Methode zur Auflistung von Tools verwendet, um alle Tools abzurufen und sie in der UI anzuzeigen.
```
entry_points={
      "package_tools": ["<your_tool_name> = <list_module>:<list_method>"],
},
```
[!Hinweis] Sie müssen diese Datei nicht aktualisieren, wenn Sie die vorhandene Ordnerstruktur beibehalten.

Verwenden Sie Ihr Tool aus der VSCode-Erweiterung#

Schritt 1: Installieren Sie die Prompt Flow for VS Code-Erweiterung.

Schritt 2: Gehen Sie zum Terminal und installieren Sie Ihr Tool-Paket in der Conda-Umgebung der Erweiterung. Angenommen, Ihr Conda-Umgebungsname ist prompt-flow.

(local_test) PS D:\projects\promptflow\tool-package-quickstart> conda activate prompt-flow
(prompt-flow) PS D:\projects\promptflow\tool-package-quickstart> pip install .\dist\my_tools_package-0.0.1-py3-none-any.whl

Schritt 3: Gehen Sie zur Erweiterung und öffnen Sie einen Flow-Ordner. Klicken Sie auf „flow.dag.yaml“ und zeigen Sie eine Vorschau des Flows an. Klicken Sie dann auf die Schaltfläche + und Sie sehen Ihre Tools. Möglicherweise müssen Sie die Fenster neu laden, um den vorherigen Cache zu leeren, wenn Sie Ihr Tool nicht in der Liste sehen.

FAQs#

Warum wird mein benutzerdefiniertes Tool nicht in der UI angezeigt?#

Bestätigen Sie, dass die Tool-YAML-Dateien in Ihrem benutzerdefinierten Tool-Paket enthalten sind. Sie können die YAML-Dateien zu MANIFEST.in hinzufügen und die Paketdaten in setup.py einbeziehen. Alternativ können Sie Ihr Tool-Paket mit dem folgenden Skript testen, um sicherzustellen, dass Sie Ihre Tool-YAML-Dateien gepackt und den Paket-Tool-Einstiegspunkt korrekt konfiguriert haben.

Stellen Sie sicher, dass Sie das Tool-Paket in Ihrer Conda-Umgebung installieren, bevor Sie dieses Skript ausführen.

Erstellen Sie irgendwo eine Python-Datei und kopieren Sie den folgenden Inhalt hinein.

import importlib
import importlib.metadata

def test():
    """List all package tools information using the `package-tools` entry point.

    This function iterates through all entry points registered under the group "package_tools."
    For each tool, it imports the associated module to ensure its validity and then prints
    information about the tool.

    Note:
    - Make sure your package is correctly packed to appear in the list.
    - The module is imported to validate its presence and correctness.

    Example of tool information printed:
    ----identifier
    {'module': 'module_name', 'package': 'package_name', 'package_version': 'package_version', ...}
    """
    entry_points = importlib.metadata.entry_points()
    if hasattr(entry_points, "select"):
        entry_points = entry_points.select(group=PACKAGE_TOOLS_ENTRY)
    else:
        entry_points = entry_points.get(PACKAGE_TOOLS_ENTRY, [])
    for entry_point in entry_points:
        list_tool_func = entry_point.load()
        package_tools = list_tool_func()

        for identifier, tool in package_tools.items():
            importlib.import_module(tool["module"])  # Import the module to ensure its validity
            print(f"----{identifier}\n{tool}")

if __name__ == "__main__":
    test()

Führen Sie dieses Skript in Ihrer Conda-Umgebung aus. Dies gibt die Metadaten aller lokal installierten Tools zurück, und Sie sollten überprüfen, ob Ihre Tools aufgelistet sind.

Warum kann ich kein Paket auf PyPI hochladen?#

Stellen Sie sicher, dass der eingegebene Benutzername und das Passwort Ihres PyPI-Kontos korrekt sind.
Wenn Sie einen 403 Forbidden Error erhalten, liegt dies wahrscheinlich an einem Namenskonflikt mit einem vorhandenen Paket. Sie müssen einen anderen Namen wählen. Paketnamen müssen auf PyPI eindeutig sein, um Verwechslungen und Konflikte zwischen Benutzern zu vermeiden. Bevor Sie ein neues Paket erstellen, wird empfohlen, PyPI (https://pypi.org/) zu durchsuchen, um zu überprüfen, ob der gewünschte Name nicht bereits vergeben ist. Wenn der gewünschte Name nicht verfügbar ist, sollten Sie einen alternativen Namen oder eine Variante wählen, die Ihr Paket klar vom vorhandenen unterscheidet.