Verbindungen verwalten

Verbindungen helfen dabei, geheime Schlüssel oder andere sensible Anmeldeinformationen sicher zu speichern und zu verwalten, die für die Interaktion mit LLMs (Large Language Models) und anderen externen Tools, z. B. Azure Content Safety, erforderlich sind.

Hinweis

Dieses Dokument richtet sich an die lokale Verwaltung von Verbindungen. Für die Verwendung von Azure AI-Verbindungen lokal siehe diesen Leitfaden.

Verbindungstypen

In Promptflow werden mehrere Verbindungstypen unterstützt, die einfach in stark typisierte Verbindungen und benutzerdefinierte Verbindungen eingeteilt werden können. Stark typisierte Verbindungen umfassen AzureOpenAIConnection, OpenAIConnection usw. Die benutzerdefinierte Verbindung ist ein generischer Verbindungstyp, der zum Speichern benutzerdefinierter Anmeldeinformationen verwendet werden kann.

Wir werden AzureOpenAIConnection als Beispiel für stark typisierte Verbindungen und CustomConnection verwenden, um zu zeigen, wie Verbindungen verwaltet werden.

Eine Verbindung erstellen

Hinweis

Wenn Sie WSL oder ein anderes Betriebssystem ohne standardmäßigen Keyring-Speicher-Backend verwenden, können Sie auf StoreConnectionEncryptionKeyError stoßen. Weitere Informationen finden Sie im FAQ.

CLI

Jede stark typisierte Verbindung hat ein entsprechendes YAML-Schema. Das folgende Beispiel zeigt das 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"

Das YAML für benutzerdefinierte Verbindungen enthält zwei Wörterbuchfelder für Secrets und Configs. Das folgende Beispiel zeigt das 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>"

Nachdem Sie die YAML-Datei vorbereitet haben, verwenden Sie den folgenden CLI-Befehl, um sie zu erstellen.

# 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>

Das erwartete Ergebnis ist wie folgt, wenn die Verbindung erfolgreich erstellt wurde.

SDK

Mit dem SDK hat jeder Verbindungstyp eine entsprechende Klasse zur Erstellung einer Verbindung. Der folgende Codeausschnitt zeigt, wie die erforderliche Klasse importiert und die Verbindung erstellt wird.

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-Erweiterung

In der Hauptseitenleiste von VS Code > im Promptflow-Bereich. Sie finden den Verbindungsbereich, um Ihre lokalen Verbindungen zu verwalten. Klicken Sie auf das "+"-Symbol oben rechts und folgen Sie den angezeigten Anweisungen, um Ihre neue Verbindung zu erstellen.

Eine Verbindung aktualisieren

CLI

Die folgenden Befehle zeigen, wie bestehende Verbindungen mit neuen Werten aktualisiert werden.

# 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

Der folgende Codeausschnitt zeigt, wie bestehende Verbindungen mit neuen Werten aktualisiert werden.

# 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-Erweiterung

In der Hauptseitenleiste von VS Code > im Promptflow-Bereich. Sie finden den Verbindungsbereich, um Ihre lokalen Verbindungen zu verwalten. Klicken Sie mit der rechten Maustaste auf das Element in der Verbindungsliste, um Ihre Verbindungen zu aktualisieren oder zu löschen.

Verbindungen auflisten

CLI

Der Befehl zum Auflisten von Verbindungen gibt die Verbindungen im JSON-Listenformat zurück. Beachten Sie, dass alle Geheimnisse und API-Schlüssel geschwärzt werden.

pf connection list

SDK

Der Befehl zum Auflisten von Verbindungen gibt die Liste der Verbindungsobjekte zurück. Beachten Sie, dass alle Geheimnisse und API-Schlüssel geschwärzt werden.

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-Erweiterung

Eine Verbindung löschen

CLI

Löschen Sie eine Verbindung mit dem folgenden Befehl.

pf connection delete -n <connection_name>

SDK

Löschen Sie eine Verbindung mit dem folgenden Codeausschnitt.

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-Erweiterung

In der Hauptseitenleiste von VS Code > im Promptflow-Bereich. Sie finden den Verbindungsbereich, um Ihre lokalen Verbindungen zu verwalten. Klicken Sie mit der rechten Maustaste auf das Element in der Verbindungsliste, um Ihre Verbindungen zu aktualisieren oder zu löschen.

Aus Umgebungsvariablen laden

Mit promptflow>=1.8.0 kann der Benutzer ein Verbindungsobjekt aus OS-Umgebungsvariablen mit der Funktion <ConnectionType>.from_env laden. Beachten Sie, dass das Verbindungsobjekt NICHT in der lokalen Datenbank erstellt wird.

Unterstützte Typen sind wie folgt:

Verbindungstyp	Feld	Zugehörige Umgebungsvariable
OpenAIConnection	api_key	OPENAI_API_KEY
	organization	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

Wenn beispielsweise OPENAI_API_KEY in der Umgebung gesetzt ist, kann ein OpenAIConnection-Objekt mit OpenAIConnection.from_env() geladen werden.

Authentifizierung mit Microsoft Entra ID

Microsoft Entra ID ist ein cloudbasierter Identitäts- und Zugriffsverwaltungsdienst, der Ihren Mitarbeitern den Zugriff auf externe Ressourcen ermöglicht.

Einige Promptflow-Verbindungstypen unterstützen die Verbindung Authentifizierung mit Microsoft Entra ID.

Verbindungstyp	YAML-Feld	Wert	Paketanforderungen	VS Code-Erweiterung
AzureOpenAIConnection	auth_mode	meid_token	promptflow[azureml-serving]>=1.7.0, promptflow-tools>=1.4.0	1.20.0

Nächste Schritte

• Weitere Details zu Verbindungskonzepten.

• Probieren Sie die Verbindungsbeispiele aus.

• Verbindungen von Azure AI verbrauchen.