管理连接

Connection 帮助安全地存储和管理与LLM（大型语言模型）和其他外部工具（例如Azure内容安全）交互所需的密钥或其他敏感凭证。

注意

本文档旨在本地管理连接。要在本地使用Azure AI连接，请参考本指南。

连接类型

在promptflow中支持多种类型的连接，可以简单地分为强类型连接和自定义连接。强类型连接包括AzureOpenAIConnection、OpenAIConnection等。自定义连接是一种通用连接类型，可用于存储自定义的凭据。

我们将使用 AzureOpenAIConnection 作为强类型连接的示例，并使用 CustomConnection 来展示如何管理连接。

创建一个连接

注意

如果您正在使用WSL或其他没有默认密钥环存储后端的操作系统，您可能会遇到StoreConnectionEncryptionKeyError，请参考FAQ以获取解决方案。

CLI

每个强类型连接都有一个对应的 yaml 模式，下面的示例展示了 AzureOpenAIConnection 的 yaml：

$schema: https://azuremlschemas.azureedge.net/promptflow/latest/AzureOpenAIConnection.schema.json
name: azure_open_ai_connection
type: azure_open_ai
api_key: "<to-be-replaced>"
api_base: "https://<name>.openai.azure.com/"
api_type: "azure"
api_version: "2023-03-15-preview"

自定义连接的yaml将有两个字典字段用于存储密钥和配置，下面的示例展示了CustomConnection yaml：

$schema: https://azuremlschemas.azureedge.net/promptflow/latest/CustomConnection.schema.json
name: custom_connection
type: custom
configs:
  endpoint: "<your-endpoint>"
  other_config: "other_value"
secrets:  # required
  my_key: "<your-api-key>"

准备好yaml文件后，使用以下CLI命令创建它们：

# Override keys with --set to avoid yaml file changes
pf connection create -f <path-to-azure-open-ai-connection> --set api_key=<your-api-key>
# Create the custom connection
pf connection create -f <path-to-custom-connection> --set configs.endpoint=<endpoint> secrets.my_key=<your-api-key>

如果连接成功创建，预期结果如下。

SDK

使用SDK，每种连接类型都有一个对应的类来创建连接。以下代码片段展示了如何导入所需的类并创建连接：

from promptflow.client import PFClient
from promptflow.entities import AzureOpenAIConnection, CustomConnection

# Get a pf client to manage connections
pf = PFClient()

# Initialize an AzureOpenAIConnection object
connection = AzureOpenAIConnection(
    name="my_azure_open_ai_connection", 
    api_key="<your-api-key>", 
    api_base="<your-endpoint>",
    api_version="2023-03-15-preview"
)

# Create the connection, note that api_key will be scrubbed in the returned result
result = pf.connections.create_or_update(connection)
print(result)

# Initialize a custom connection object
connection = CustomConnection(
    name="my_custom_connection", 
    # Secrets is a required field for custom connection
    secrets={"my_key": "<your-api-key>"},
    configs={"endpoint": "<your-endpoint>", "other_config": "other_value"}
)

# Create the connection, note that all secret values will be scrubbed in the returned result
result = pf.connections.create_or_update(connection)
print(result)

VS Code Extension

在VS Code主侧边栏 > 提示流面板中。您可以找到连接面板来管理您的本地连接。点击右上角的“+”图标，并按照弹出的指示创建您的新连接。

更新连接

CLI

以下命令展示了如何使用新值更新现有连接：

# Update an azure OpenAI connection with a new api base
pf connection update -n my_azure_open_ai_connection --set api_base='new_value'
# Update a custom connection
pf connection update -n my_custom_connection --set configs.other_config='new_value'

SDK

下面的代码片段展示了如何用新值更新现有连接：

# Update an azure OpenAI connection with a new api base
connection = pf.connections.get(name="my_azure_open_ai_connection")
connection.api_base = "new_value"
connection.api_key = "<original-key>"  # secrets are required when updating connection using sdk
result = pf.connections.create_or_update(connection)
print(connection)
# Update a custom connection
connection = pf.connections.get(name="my_custom_connection")
connection.configs["other_config"] = "new_value"
connection.secrets = {"key1": "val1"}  # secrets are required when updating connection using sdk
result = pf.connections.create_or_update(connection)
print(connection)

VS Code Extension

在VS Code主侧边栏 > 提示流面板中。您可以找到连接面板来管理您的本地连接。右键单击连接列表中的项目以更新或删除您的连接。

列出连接

CLI

列出连接命令将以json列表格式返回连接，请注意所有密钥和api密钥将被清除：

pf connection list

SDK

列出连接命令将返回连接对象列表，请注意所有密钥和API密钥将被清除：

from promptflow.client import PFClient
# Get a pf client to manage connections
pf = PFClient()
# List and print connections
connection_list = pf.connections.list()
for connection in connection_list:
    print(connection)

VS Code Extension

删除一个连接

CLI

使用以下命令删除连接：

pf connection delete -n <connection_name>

SDK

使用以下代码片段删除连接：

from promptflow.client import PFClient

# Get a pf client to manage connections
pf = PFClient()
# Delete the connection with specific name
pf.connections.delete(name="my_custom_connection")

VS Code Extension

在VS Code主侧边栏 > 提示流面板。您可以找到连接面板来管理您的本地连接。右键单击连接列表中的项目以更新或删除您的连接。

从环境变量加载

使用 promptflow>=1.8.0，用户能够通过 .from_env 函数从操作系统环境变量中加载连接对象。 请注意，连接对象将 不会创建 到本地数据库。

支持的类型如下：

连接类型	字段	相关环境变量
OpenAIConnection	api_key	OPENAI_API_KEY
	组织	OPENAI_ORG_ID
	base_url	OPENAI_BASE_URL
AzureOpenAIConnection	api_key	AZURE_OPENAI_API_KEY
	api_base	AZURE_OPENAI_ENDPOINT
	api_version	OPENAI_API_VERSION

例如，当OPENAI_API_KEY设置为环境变量时，可以使用OpenAIConnection.from_env()加载一个OpenAIConnection对象。

使用 Microsoft Entra ID 进行身份验证

Microsoft Entra ID 是一个基于云的身份和访问管理服务，使您的员工能够访问外部资源。

一些promptflow连接类型支持使用Microsoft Entra ID进行连接认证。

连接类型	Yaml字段	值	包要求	VS Code扩展
AzureOpenAIConnection	auth_mode	meid_token	promptflow[azureml-serving]>=1.7.0, promptflow-tools>=1.4.0	1.20.0

下一步

• 了解更多关于连接概念的详细信息。

• 尝试连接示例。

• 从Azure AI消费连接。