创建和使用工具包#

在本文档中，我们将指导您完成开发自己的工具包的过程，提供详细的步骤和如何使用您的创作的建议。

自定义工具是您自己开发的 Prompt flow 工具。如果您觉得它很有用，可以按照此指南将其制作成工具包。这将使您能够方便地重用它，与您的团队共享，或分发给世界上的任何人。

成功安装包后，您的自定义“工具”将如下所示显示在 VSCode 扩展中： custom-tool-list

创建您自己的工具包#

您的工具包应该是一个 python 包。要快速尝试，只需使用 my-tools-package 0.0.1 并跳过此部分。

先决条件#

使用 python 3.9 或 3.10 创建新的 conda 环境。运行以下命令安装 PromptFlow 依赖项

pip install promptflow

安装 Pytest 包以运行测试

pip install pytest pytest-mock

使用以下命令从 GitHub 克隆 PromptFlow 存储库

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

创建自定义工具包#

在根文件夹下运行以下命令以快速创建您的工具项目

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>

例如

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

这个自动生成的脚本将为您创建一个工具。参数 destination 和 package-name 是强制性的。参数 tool-name 和 function-name 是可选的。如果未填写，tool-name 将默认为 hello_world_tool，function-name 将默认为 tool-name。

该命令将生成如下所示的工具项目，其中包含一个工具 hello_world_tool.py

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

以下 几点 解释了 包中每个文件夹/文件的 目的。如果您的 目标是 在您的 包中 开发 多个 工具，请 务必 仔细 检查 第 2 点 和 第 5 点。

  1. hello-world-proj：这是源目录。您项目的所有源代码都应放在此目录中。

  2. hello-world/tools：此目录包含您项目的各个工具。您的工具包可以包含一个工具或多个工具。添加新工具时，您应该在 tools 文件夹下创建另一个 *_tool.py。

  3. hello-world/tools/hello_world_tool.py：在 def 函数中开发您的工具。使用 @tool 装饰器将函数标识为工具。

    [!Note] 有两种编写工具的方法。默认和推荐的方法是函数实现方式。您也可以使用类实现方式，请参考 my_tool_2.py 作为示例。

  4. hello-world/tools/utils.py：此文件实现工具列表方法，该方法收集所有定义的工具。此工具列表方法是必需的，因为它允许用户界面 (UI) 检索您的工具并在 UI 中显示它们。

    [!Note] 如果您保持现有的文件夹结构，则无需创建自己的列表方法。您可以简单地使用 utils.py 文件中提供的自动生成的列表方法。

  5. hello_world/yamls/hello_world_tool.yaml：工具 YAML 定义了工具的元数据。utils.py 中概述的工具列表方法会获取这些工具 YAML。

    [!Note] 如果您创建了一个新工具，请不要忘记也创建相应的工具 YAML。您可以在工具项目下运行以下命令来自动生成您的工具 YAML。您可能需要为 name 指定 -n，为 description 指定 -d，它们将作为工具名称和提示流 UI 中的工具提示显示。

    python <promptflow github repo>\scripts\tool\generate_package_tool_meta.py -m <tool_module> -o <tool_yaml_path> -n <tool_name> -d <tool_description>

    例如

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

    要填充您的工具模块，请遵循模式 <package_name>.tools.<tool_name>，它表示包中工具的文件夹路径。

  6. tests：此目录包含所有测试，尽管它们不是创建自定义工具包所必需的。添加新工具时，您还可以创建相应的测试并将其放在此目录中。在工具项目下运行以下命令

    pytest tests

  7. MANIFEST.in：此文件用于确定要包含在项目分发中的文件。工具 YAML 文件应包含在 MANIFEST.in 中，以便您的工具 YAML 将被打包，并且您的工具可以在 UI 中显示。

    [!Note] 如果您保持现有的文件夹结构，则无需更新此文件。

  8. setup.py：此文件包含有关您项目的元数据，例如名称、版本、作者等。此外，入口点在 generate_tool_package_template.py 脚本中为您自动配置。在 Python 中，在 setup.py 中配置入口点有助于建立包的主要执行点，从而简化其与其他软件的集成。

    package_tools 入口点与工具列表方法一起用于检索所有工具并在 UI 中显示它们。

    entry_points={
      "package_tools": ["<your_tool_name> = <list_module>:<list_method>"],
},

    [!Note] 如果您保持现有的文件夹结构，则无需更新此文件。

构建和共享工具包#

在工具包根目录下执行以下命令来构建您的工具包

python setup.py sdist bdist_wheel

这将在 dist 文件夹中生成一个工具包 <your-package>-0.0.1.tar.gz 和相应的 whl file。

如果您还没有 PyPI 帐户，请创建一个，并通过运行 pip install twine 命令安装 twine 包。

通过运行 twine upload dist/* 将您的包上传到 PyPI，这会提示您输入 PyPI 用户名和密码，然后将您的包上传到 PyPI。一旦您的包上传到 PyPI，其他人就可以通过运行 pip install your-package-name 使用 pip 安装它。请务必将 your-package-name 替换为您的包在 PyPI 上显示的名称。

如果您只想将其放在 Test PyPI 上，请通过运行 twine upload --repository-url https://test.pypi.org/legacy/ dist/* 上传您的包。一旦您的包上传到 Test PyPI，其他人就可以通过运行 pip install --index-url https://test.pypi.org/simple/ your-package-name 使用 pip 安装它。

从 VSCode 扩展使用您的工具#

  • 步骤1：安装 Prompt flow for VS Code 扩展。

  • 步骤2：转到终端并在扩展的 conda 环境中安装您的工具包。假设您的 conda 环境名称是 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

  • 步骤3：转到扩展并打开一个流文件夹。单击“flow.dag.yaml”并预览流。接下来，单击 + 按钮，您将看到您的工具。如果您在列表中看不到您的工具，可能需要重新加载窗口以清除之前的缓存。auto-list-tool-in-extension

常见问题#

为什么我的自定义工具没有显示在 UI 中？#

确认工具 YAML 文件包含在您的自定义工具包中。您可以将 YAML 文件添加到 MANIFEST.in，并将包数据包含在 setup.py 中。或者，您可以使用以下脚本测试您的工具包，以确保您已正确打包您的工具 YAML 文件并配置了包工具入口点。

  1. 在执行此脚本之前，请务必在您的 conda 环境中安装工具包。

  2. 在任何地方创建一个 python 文件，并将以下内容复制到其中。

    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()

  3. 在您的 conda 环境中运行此脚本。这将返回安装在您的本地环境中的所有工具的元数据，您应该验证您的工具是否已列出。

为什么我无法将包上传到 PyPI？#

  • 确保输入的 PyPI 帐户用户名和密码准确无误。

  • 如果您遇到 403 Forbidden Error，很可能是由于与现有包的命名冲突。您需要选择一个不同的名称。包名称在 PyPI 上必须是唯一的，以避免用户之间的混淆和冲突。在创建新包之前，建议搜索 PyPI (https://pypi.ac.cn/) 以验证您选择的名称是否已被占用。如果您想要的名称不可用，请考虑选择一个替代名称或一个能够清晰区分您的包与现有包的变体。

高级功能#