使用Mirascope CLI

处理提示和调用时最令人沮丧的主要问题之一是跟踪所有各种修订版本。从alembic和git中汲取灵感，Mirascope CLI提供了一些关键命令，使管理提示和调用更加容易。

安装

要仅安装CLI，您可以运行

pip install mirascope-cli

如果您正在使用mirascope包，您还可以将CLI作为额外依赖项安装

pip install mirascope[cli]  # just the mirascope-cli
pip install mirascope[all]  # all optional dependencies

提示管理环境

使用Mirascope CLI的第一步是在项目的根目录中运行init命令。

mirascope init

这将为管理提示和调用创建目录和文件。以下是init函数创建的示例结构

|
|-- mirascope.ini
|-- mirascope
|   |-- prompt_template.j2
|   |-- versions/
|   |   |-- <directory_name>/
|   |   |   |-- version.txt
|   |   |   |-- <revision_id>_<directory_name>.py
|-- prompts/

以下是每个目录和文件的概述

• mirascope.ini - 可以根据项目自定义的INI文件
• mirascope - 存储提示管理环境的目录的默认名称
• prompt_template.j2 - 用于生成提示版本的Jinja2模板文件
• versions - 存储各种提示版本的目录
• versions/<directory_name - 为prompts目录中的每个提示文件创建的子目录
• version.txt - 一种跟踪当前和最新修订版本的方法。即将推出使用数据库的修订跟踪
• <revision_id>_<directory_name>.py - 由mirascope add命令创建的提示版本，稍后将详细介绍。
• prompts - 存储所有提示和调用文件的用户的目录

可以通过修改mirascope.ini文件或在运行init命令时更改目录名称。

mirascope init --mirascope_location my_mirascope --prompts_location calls

保存第一个提示

创建提示管理目录后，您现在可以构建和迭代一些提示了。首先，将一个Mirascope提示添加到提示目录。

# prompts/book_recommender.py
from mirascope.openai import OpenAICall, OpenAICallParams


class BookRecommender(OpenAICall):
    prompt_template = "Can you recommend some books on {topic} in a list format?"

    topic: str
    
    call_params = OpenAICallParams(model="gpt-3.5-turbo")

一旦您对第一个迭代的提示满意，您可以运行

mirascope add book_recommender

这将把book_recommender.py提交到您的versions/目录，创建一个book_recommender子目录和一个0001_book_recommender.py。

以下是0001_book_recommender.py的样貌

# versions/book_recommender/0001_book_recommender.py
from mirascope.openai import OpenAICall, OpenAICallParams

prev_revision_id = "None"
revision_id = "0001"


class BookRecommender(OpenAICall):
    prompt_template = "Can you recommend some books on {topic} in a list format?"

    topic: str
    
    call_params = OpenAICallParams(model="gpt-3.5-turbo")

versions目录中的提示几乎与prompts目录中的提示相同，只有一些差异。

prev_revision_id和revision_id变量将用于即将推出的功能，请关注更新。

协同定位

影响提示质量的任何内容都存在于提示中。这就是为什么在BaseCall中存在call_params，以及为什么OpenAICall和其他提供者包装器扩展了BasePrompt类。

迭代提示

现在，这个版本的book_recommender已经保存，您可以自由地修改原始的book_recommender.py并进行迭代。也许，您想切换到不同的提供者并比较结果。

以下是book_recommender.py的下一个迭代版本

# prompts/book_recommender.py
from google.generativeai import configure
from mirasope.gemini import GeminiCall, GeminiCallParams

configure(api_key="YOUR_GEMINI_API_KEY")


class BookRecommender(GeminiCall):
	prompt_template = "Can you recommend some books on {topic} in a list format?"

	ingredient: str

	call_params = GeminiCallParams(model="gemini-1.0-pro")

在添加下一个版本的my_prompt之前，您可能想检查提示的状态。

# You can specify a specific prompt
mirascope status my_prompt

# or, you can check the status of all prompts
mirascope status

请注意，在运行add或use命令之前，也会检查状态。现在我们可以运行上一节中的相同add命令来提交另一个版本0002_book_recommender.py

切换版本

您现在可以自由地切换不同的提供者或使用同一提供者的不同模型来迭代到最佳结果。

您可以使用use命令快速切换提示

mirascope use book_recommender 0001

在此处指定您想要使用的提示和版本。这将使用versions/0001_book_recommender.py的内容更新您的prompts/book_recommender.py（不包括内部使用的变量）。

这可以让您快速交换提示或提供者而无需更改代码，除非提示具有不同的属性。在这种情况下，您的linter将检测需要解决的缺少或额外的属性。

删除提示

在实验提示时，您的项目中可能需要清理大量的实验提示。

您可以使用remove命令删除任何版本

mirascope remove book_recommender 0001

在此处指定您想要删除的提示和版本。删除将删除文件，但也会将具有被删除版本的任何版本的prev_revision_id更新为None。

[!注意] 如果current_revision与您尝试删除的提示相同，则mirascope remove不会删除提示。如果您有即将到来的更改，可以使用mirascope add，或者使用mirascope use来交换current_revision。

Mirascope INI

Mirascope INI为您提供了某些定制。请随意更新任何字段。

[mirascope]

# path to mirascope directory
mirascope_location = .mirascope

# path to versions directory
versions_location = %(mirascope_location)s/versions

# path to prompts directory
prompts_location = prompts

# name of versions text file
version_file_name = version.txt

# formats the version file
# leave blank to not format 
format_command = ruff check --select I --fix; ruff format

# auto tag prompts with version
auto_tag = True

• auto_tag - 向Mirascope提示添加@tags(["version:0001"])。如果添加了新版本，这将自动递增版本号。

未来更新

还有更多内容可以添加到Mirascope CLI。以下是我们计划添加的一些内容的列表，不分先后：

• 提示比较 - 使用黄金测试比较两个不同版本的方法
• 历史记录 - 查看版本的修订历史
• 测试 - 将输入和输出添加到版本以进行CI测试

如果您想实现某些功能，或者如果您认为某些功能有用但未在此列表中，请告诉我们！