Poznámka:
Přístup k této stránce vyžaduje autorizaci. Můžete se zkusit přihlásit nebo změnit adresáře.
Přístup k této stránce vyžaduje autorizaci. Můžete zkusit změnit adresáře.
Important
Pro nové případy použití doporučuje Databricks nasazovat agenty v Databricks Apps, aby bylo možné plně řídit kód agenta, konfiguraci serveru a pracovní postup nasazení. Viz Vytvoření agenta AI a jeho nasazení v Databricks Apps. Pokud chcete migrovat existujícího agenta, přečtěte si téma Migrace agenta z modelové obsluhy do Databricks Apps.
Agenti umělé inteligence se často potřebují ověřit v jiných prostředcích, aby mohli provádět úlohy. Nasazený agent může například potřebovat přístup k indexu služby AI Search, aby se dotazoval na nestrukturovaná data nebo registr výzvy k načtení dynamických výzev.
Tato stránka popisuje metody ověřování dostupné při vývoji a nasazování agentů pomocí vlastních agentů.
Metody ověřování
Následující tabulka porovnává dostupné metody ověřování. Můžete kombinovat a libovolně míchat různé z těchto přístupů:
| Metoda | Description | Stav zabezpečení | Složitost nastavení |
|---|---|---|---|
| Průchozí ověřování | Agent běží s oprávněními uživatele, který ho nasadil. Databricks automaticky spravuje krátkodobé přihlašovací údaje pro deklarované prostředky. |
Krátkodobé přihlašovací údaje, automatická obměna | Nízká – deklarujte závislosti v době protokolování. |
| Ověřování jménem uživatele (OBO) | Agent běží s oprávněními koncového uživatele, který žádost provede. | Používá přihlašovací údaje koncového uživatele s omezenými obory. | Střední – vyžaduje deklaraci oboru a inicializaci modulu runtime. |
| Ruční ověřování | Explicitní zadání přihlašovacích údajů pomocí proměnných prostředí | Dlouhodobé přihlašovací údaje vyžadují správu rotace. | Vysoká – vyžaduje ruční správu přihlašovacích údajů. |
Volba správné metody ověřování pro váš prostředek
Pomocí tohoto vývojového diagramu můžete pro každý prostředek zvolit správnou metodu ověřování. Metody můžete podle potřeby kombinovat a agent může pro každý prostředek v závislosti na případu použití použít jinou metodu.
Vyžaduje se řízení přístupu pro jednotlivé uživatele nebo auditování s atributy uživatele?
- Ano → Použít ověřování jménem uživatele
- Žádná → Pokračovat krokem 2
Podporují všechny prostředky automatické ověřování?
- Ano → Použít Automatické předávání ověření (doporučeno)
- Nepoužívat → ruční ověřování
Přihlásit se na servery MCP služby Databricks
Pokud se chcete ověřit na serverech Databricks MCP, zadejte všechny prostředky, které agent potřebuje při logování.
Pokud například váš agent používá níže uvedené adresy URL serveru MCP, musíte ve schématech prod.customer_support a prod.billing specifikovat všechny indexy AI Search. Musíte také zadat všechny funkce katalogu Unity v prod.billing:
https://<your-workspace-hostname>/api/2.0/mcp/ai-search/prod/customer_supporthttps://<your-workspace-hostname>/api/2.0/mcp/ai-search/prod/billinghttps://<your-workspace-hostname>/api/2.0/mcp/functions/prod/billing
Pokud chcete zjednodušit proces identifikace všech závislých prostředků pro spravované servery MCP, použijte databricks-mcp balíček databricks_mcp.DatabricksMCPClient().get_databricks_resources(<server_url>) PyPI k načtení prostředků potřebných spravovaným serverem MCP.
Pokud váš agent dotazuje vlastní server MCP hostovaný v aplikaci Databricks, můžete při protokolování modelu explicitně nakonfigurovat autorizaci zahrnutím serveru jako prostředku.
Automatický průchod ověřením
Automatický průchod autentizace je nejjednodušší způsob, jak se dostat k prostředkům spravovaným službou Databricks. Stanovte závislosti zdrojů při zaznamenávání aktivit agenta a Databricks automaticky zřizuje, obměňuje a spravuje krátkodobé přihlašovací údaje během nasazení agenta.
Toto chování ověřování je podobné chování přihlášení jako vlastník u řídicích panelů Databricks. Podřízené prostředky, jako jsou tabulky katalogu Unity, jsou přístupné pomocí přihlašovacích údajů service principala s nejmenšími možnými oprávněními pouze k prostředkům, které agent potřebuje.
Jak funguje automatické předávání ověřování
Když je agent obsluhován za koncovým bodem s využitím automatického předávání ověřování, Databricks provede tyto kroky:
Ověření oprávnění: Databricks ověřuje, že tvůrce koncového bodu má přístup ke všem závislostem zadaným během protokolování agenta.
Vytváření a udělování oprávnění služebního účtu: Služební účet je vytvořen pro verzi modelu agenta a automaticky mu je udělen přístup k prostředkům agenta pro čtení.
Note
Objekt "service principal" generovaný systémem se nezobrazuje v seznamech API ani uživatelského rozhraní. Pokud je z koncového bodu odstraněna verze modelu agenta, bude odstraněn také principál služby.
Zřizování a rotace přihlašovacích údajů: Krátkodobé přihlašovací údaje (token OAuth M2M) pro principál služby jsou vloženy do koncového bodu, což agentovému kódu umožňuje přistupovat k prostředkům Databricks. Databricks také obměňuje přihlašovací údaje, což zajišťuje, že váš agent má nepřetržitý a zabezpečený přístup k závislým prostředkům.
Podporované zdroje pro automatický přenos ověřování
Následující tabulka uvádí prostředky Databricks, podporující automatické předávání ověřování, a oprávnění, která musí mít tvůrce koncového bodu při nasazování agenta.
Note
Prostředky katalogu Unity rovněž potřebují USE SCHEMA na nadřazeném schématu a USE CATALOG na nadřazeném katalogu.
| Typ zdroje | Povolení | Minimální verze MLflow |
|---|---|---|
| Datový sklad SQL | Use Endpoint |
2.16.1 nebo novější |
| Koncový bod pro obsluhu modelu | Can Query |
2.13.1 nebo novější |
| Funkce katalogu Unity | EXECUTE |
2.16.1 nebo novější |
| Genie Agent | Can Run |
2.17.1 nebo vyšší |
| Index vyhledávání AI | Can Use |
2.13.1 nebo novější |
| Tabulka katalogu Unity | SELECT |
2.18.0 nebo vyšší |
| Připojení katalogu Unity | Use Connection |
2.17.1 nebo vyšší |
| Lakebase | databricks_superuser |
3.3.2 nebo vyšší |
Implementace automatického předávání ověřování
Pokud chcete povolit automatické přeposílání ověřování, zadejte závislé prostředky při logování agenta. Použijte parametr resources rozhraní log_model() API.
Note
Nezapomeňte také protokolovat všechny podřízené závislé prostředky. Pokud například protokolujete agenta Genie, musíte také protokolovat jeho tabulky, služby SQL Warehouse a funkce katalogu Unity.
import mlflow
from mlflow.models.resources import (
DatabricksVectorSearchIndex,
DatabricksServingEndpoint,
DatabricksSQLWarehouse,
DatabricksFunction,
DatabricksGenieSpace,
DatabricksTable,
DatabricksUCConnection,
DatabricksApp,
DatabricksLakebase
)
with mlflow.start_run():
logged_agent_info = mlflow.pyfunc.log_model(
python_model="agent.py",
artifact_path="agent",
input_example=input_example,
example_no_conversion=True,
# Specify resources for automatic authentication passthrough
resources=[
DatabricksVectorSearchIndex(index_name="prod.agents.databricks_docs_index"),
DatabricksServingEndpoint(endpoint_name="databricks-meta-llama-3-3-70b-instruct"),
DatabricksServingEndpoint(endpoint_name="databricks-bge-large-en"),
DatabricksSQLWarehouse(warehouse_id="your_warehouse_id"),
DatabricksFunction(function_name="ml.tools.python_exec"),
DatabricksGenieSpace(genie_space_id="your_genie_space_id"),
DatabricksTable(table_name="your_table_name"),
DatabricksUCConnection(connection_name="your_connection_name"),
DatabricksApp(app_name="app_name"),
DatabricksLakebase(database_instance_name="lakebase_instance_name"),
]
)
Ověřování jménem uživatele
Important
Tato funkce je ve verzi Public Preview.
Ověřování jménem uživatele (OBO) umožňuje agentovi jednat jako uživatel Databricks, který spouští dotaz. To poskytuje:
- Přístup jednotlivých uživatelů k citlivým datům
- Jemná kontrola dat vynucovaná katalogem Unity
- Tokeny zabezpečení jsou omezené ("downscoped") pouze na rozhraní API, která váš agent deklaruje, což snižuje riziko zneužití.
Požadavky
- Ověřování na základě pověření uživatele vyžaduje MLflow 2.22.1 a vyšší.
- Ověřování jménem uživatele je ve výchozím nastavení zakázané a musí ho povolit správce pracovního prostoru. Před povolením této funkce si projděte důležité informace o zabezpečení .
Podporované prostředky OBO
V koncových bodech obsluhy modelů můžou agenti s ověřováním OBO přistupovat pouze k prostředkům Databricks uvedeným v následující tabulce. Zdroje, které tu nejsou uvedené, jako například svazky katalogu Unity (nahrání nebo stažení souboru), nejsou podporované pro proces OBO při servírování modelů.
Note
Pokud váš agent vyžaduje přístup OBO k širší sadě prostředků, Doporučuje Databricks nasadit vašeho agenta v Databricks Apps, který podporuje další obory OAuth. Viz Migrace agenta z modelové obsluhy do aplikací Databricks.
| Prostředek Databricks | Kompatibilní klienti |
|---|---|
| Index vyhledávání AI |
databricks_langchain.VectorSearchRetrieverTool, databricks_openai.VectorSearchRetrieverTool, VectorSearchClient |
| Koncový bod obsluhy modelu | databricks.sdk.WorkspaceClient |
| Datový sklad SQL | databricks.sdk.WorkspaceClient |
| Spojení UC | databricks.sdk.WorkspaceClient |
| Tabulky a funkce Unified Communications |
databricks.sdk.WorkspaceClient (Pokud chcete získat přístup k tabulkám UC, musíte použít dotazy SQL pomocí rozhraní API pro spouštění příkazů SQL). |
| Genie Agent |
databricks.sdk.WorkspaceClient (doporučeno), databricks_langchain.GenieAgentnebo databricks_ai_bridge.GenieAgent |
| Protokol modelového kontextu (MCP) | databricks_mcp.DatabricksMCPClient |
Implementace ověřování OBO
Pokud chcete povolit ověřování jménem uživatele, proveďte následující kroky:
- Aktualizujte volání sady SDK a určete, že k prostředkům se přistupuje jménem koncového uživatele.
- Aktualizace kódu agenta pro inicializaci přístupu OBO uvnitř
predictfunkce, ne v__init__, protože identita uživatele je známa pouze za běhu. - Při protokolování agenta pro nasazení deklarujte obory rozhraní REST API Databricks, které agent vyžaduje.
Následující úryvky kódu ukazují, jak nakonfigurovat přístup jménem uživatele k různým prostředkům Databricks. Při inicializaci nástrojů zpracujte chyby oprávnění elegantně zabalením inicializace do try-except bloku.
Nástroj AI Search Retriever
from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials
from databricks_langchain import VectorSearchRetrieverTool
# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy = ModelServingUserCredentials())
vector_search_tools = []
# Exclude exception handling if the agent should fail
# when users lack access to all required Databricks resources
try:
tool = VectorSearchRetrieverTool(
index_name="<index_name>",
description="...",
tool_name="...",
workspace_client=user_client # Specify the user authorized client
)
vector_search_tools.append(tool)
except Exception as e:
_logger.debug("Skipping adding tool as user does not have permissions")
Klient AI Search
from databricks.vector_search.client import VectorSearchClient
from databricks.vector_search.utils import CredentialStrategy
# Configure a VectorSearch Client to use on behalf of end
# user authentication
user_authenticated_vsc = VectorSearchClient(credential_strategy=CredentialStrategy.MODEL_SERVING_USER_CREDENTIALS)
# Exclude exception handling if the agent should fail when
# users lack access to all required Databricks resources
try:
vs_index = user_authenticated_vsc.get_index(endpoint_name="endpoint_name", index_name="index_name")
...
except Exception as e:
_logger.debug("Skipping Vector Index because user does not have permissions")
MCP
from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials
from databricks_mcp import DatabricksMCPClient
# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())
mcp_client = DatabricksMCPClient(
server_url="<mcp_server_url>",
workspace_client=user_client, # Specify the user client here
)
Koncový bod obsluhy modelu
from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials
# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())
# Exclude exception handling if the agent should fail
# when users lack access to all required Databricks resources
try:
user_client.serving_endpoints.query("endpoint_name", input="")
except Exception as e:
_logger.debug("Skipping Model Serving Endpoint due to no permissions")
Spojení UC
import requests
from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials
# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())
response = requests.post(
f"{user_client.config.host}/api/2.0/unity-catalog/connections/connection_name/proxy/api/v1/resource",
headers={
**user_client.config.authenticate(),
"Content-Type": "application/json",
},
json={"key": "value"},
)
Agenti Genie (WorkspaceClient)
from databricks_langchain.genie import GenieAgent
from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials
# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())
genie_agent = GenieAgent(
genie_space_id="space-id",
genie_agent_name="Genie",
description="This Genie Agent has access to sales data in Europe",
client=user_client
)
# Use the Genie SDK methods available through WorkspaceClient
try:
response = agent.invoke("Your query here")
except Exception as e:
_logger.debug("Skipping Genie due to no permissions")
Agenti Genie (LangChain)
from databricks.sdk import WorkspaceClient
from databricks_ai_bridge import ModelServingUserCredentials
from databricks_langchain.genie import GenieAgent
# Configure a Databricks SDK WorkspaceClient to use on behalf of end
# user authentication
user_client = WorkspaceClient(credentials_strategy=ModelServingUserCredentials())
genie_agent = GenieAgent(
genie_space_id="<genie_space_id>",
genie_agent_name="Genie",
description="Genie_description",
client=user_client, # Specify the user client here
)
Inicializujte agenta ve funkci předpovědi
Vzhledem k tomu, že identita uživatele je známa pouze v době dotazu, musíte přistupovat k prostředkům OBO uvnitř predict nebo predict_stream, ne v metodě agenta __init__. Tím se zajistí oddělení prostředků mezi vyvoláním.
from mlflow.pyfunc import ResponsesAgent
class OBOResponsesAgent(ResponsesAgent):
def initialize_agent():
user_client = WorkspaceClient(
credentials_strategy=ModelServingUserCredentials()
)
system_authorized_client = WorkspaceClient()
### Use the clients above to access resources with either system or user authentication
def predict(
self, request
) -> ResponsesAgentResponse:
agent = initialize_agent() # Initialize the Agent in Predict
agent.predict(request)
...
Deklarace rozsahů rozhraní REST API při protokolování agenta
Při protokolování agenta OBO pro nasazení musíte uvést rozsahy rozhraní REST API Databricks, které agent volá jménem uživatele. Tím se zajistí, že se agent řídí principem nejnižších oprávnění: tokeny jsou omezené jenom na rozhraní API, která vyžaduje váš agent, což snižuje pravděpodobnost neoprávněné akce nebo zneužití tokenu.
V koncových bodech obsluhy modelů můžete použít pouze obory, které odpovídají výše uvedeným podporovaným prostředkům OBO .
Pokud chcete povolit ověřování jménem uživatele, předejte MLflow AuthPolicy do log_model():
import mlflow
from mlflow.models.auth_policy import AuthPolicy, SystemAuthPolicy, UserAuthPolicy
from mlflow.models.resources import DatabricksServingEndpoint
# System policy: resources accessed with system credentials
system_policy = SystemAuthPolicy(
resources=[DatabricksServingEndpoint(endpoint_name="my_endpoint")]
)
# User policy: API scopes for OBO access
user_policy = UserAuthPolicy(api_scopes=[
"model-serving",
"ai-search"
])
# Log the agent with both policies
with mlflow.start_run():
mlflow.pyfunc.log_model(
name="agent",
python_model="agent.py",
auth_policy=AuthPolicy(
system_auth_policy=system_policy,
user_auth_policy=user_policy
)
)
Ověřování OBO pro klienty OpenAI
Pro agenty, kteří používají klienta OpenAI, použijte sadu Databricks SDK k automatickému ověření během nasazování. Sada Databricks SDK obsahuje obálku pro vytvoření klienta OpenAI s automaticky nakonfigurovaným ověřováním: get_open_ai_client()
% pip install databricks-sdk[openai]
from databricks.sdk import WorkspaceClient
def openai_client(self):
w = WorkspaceClient()
return w.serving_endpoints.get_open_ai_client()
Potom zadejte koncový bod nasazení modelu v resources, aby se automaticky ověřil v době nasazení.
Důležité informace o zabezpečení OBO
Než povolíte ověřování jménem uživatele pomocí agentů, zvažte následující aspekty zabezpečení.
Rozšířený přístup k prostředkům: Agenti mají přístup k citlivým prostředkům jménem uživatelů. Zatímco obory omezují rozhraní API, koncové body můžou umožňovat více akcí, než váš agent explicitně požaduje. Obor rozhraní API například model-serving uděluje agentům oprávnění ke spuštění koncového bodu obsluhy jménem uživatele. Koncový bod obsluhy ale má přístup k dalším oborům rozhraní API, které původní agent nemá oprávnění používat.
Ukázkové poznámkové bloky OBO
Následující notebook ukazuje, jak vytvořit agenta pomocí AI Search s autorizací jménem uživatele.
Autorizace jménem uživatele pomocí AI Search
Následující poznámkový blok ukazuje, jak vytvořit agenta, který podporuje spouštění SQL ve službě SQL Warehouse pomocí autorizace jménem uživatele. To umožňuje agentu bezpečně vyvolat funkce katalogu Unity pomocí uživatelských přihlašovacích údajů.
Note
V současné době se doporučuje spouštět funkce UC s OBO, protože bezserverové spouštění Sparku s OBO se zatím nepodporuje.
Zastupování uživatele při autorizaci pomocí SQL skriptů
Ruční ověřování
Ruční ověřování umožňuje explicitně zadat přihlašovací údaje během nasazení agenta. Tato metoda má největší flexibilitu, ale vyžaduje větší nastavení a průběžnou správu přihlašovacích údajů. Tuto metodu použijte v těchto případech:
- Závislý prostředek nepodporuje automatické předání ověření.
- Agent musí používat jiné přihlašovací údaje, než jsou přihlašovací údaje nasazeného agenta.
- Agent přistupuje k externím prostředkům nebo rozhraním API mimo Databricks.
- Nainstalovaný agent přistupuje k prompt registru.
Important
Přepsání proměnných prostředí zabezpečení zakáže automatické předávání dalších prostředků, na které váš agent závisí.
Ověřování OAuth (doporučeno)
OAuth je doporučený postup ručního ověřování, protože má zabezpečené ověřování založené na tokenech pro služební identity s možností automatické obnovy tokenů.
Vytvořte instanční objekt a vygenerujte přihlašovací údaje OAuth.
Udělte principálovi služby oprávnění k jakémukoli prostředku Databricks, ke kterému má agent přístup, oprávnění pro přístup k prostředkům Databricks. Pokud chcete získat přístup k registru výzev, udělte oprávnění
CREATE FUNCTION,EXECUTE, aMANAGEke schématu katalogu Unity pro ukládání výzev.Vytvořte tajné kódy databricks pro přihlašovací údaje OAuth.
Nakonfigurujte přihlašovací údaje OAuth v kódu agenta:
import os # Configure OAuth authentication for Prompt Registry access # Replace with actual secret scope and key names secret_scope_name = "your-secret-scope" client_id_key = "oauth-client-id" client_secret_key = "oauth-client-secret" os.environ["DATABRICKS_HOST"] = "https://<your-workspace-url>" os.environ["DATABRICKS_CLIENT_ID"] = dbutils.secrets.get(scope=secret_scope_name, key=client_id_key) os.environ["DATABRICKS_CLIENT_SECRET"] = dbutils.secrets.get(scope=secret_scope_name, key=client_secret_key)Pomocí tajných kódů se připojte k pracovnímu prostoru:
w = WorkspaceClient( host=os.environ["DATABRICKS_HOST"], client_id=os.environ["DATABRICKS_CLIENT_ID"], client_secret = os.environ["DATABRICKS_CLIENT_SECRET"] )Při nasazování pomocí
agents.deploy()parametru zahrňte přihlašovací údaje OAuth jako proměnné prostředí:agents.deploy( UC_MODEL_NAME, uc_registered_model_info.version, environment_vars={ "DATABRICKS_HOST": "https://<your-workspace-url>", "DATABRICKS_CLIENT_ID": f"{{{{secrets/{secret_scope_name}/{client_id_key}}}}}", "DATABRICKS_CLIENT_SECRET": f"{{{{secrets/{secret_scope_name}/{client_secret_key}}}}}" }, )
Ověřování PAT
Ověřování PAT (Personal Access Token) poskytuje jednodušší nastavení pro vývojová a testovací prostředí, ačkoli vyžaduje více ruční správy přihlašovacích údajů:
Získejte osobní přístupový token pomocí služebního principála nebo osobního účtu:
Služební objekt (doporučeno pro zabezpečení):
- Vytvořte služební účet.
- Udělte principálovi služby oprávnění k jakémukoli prostředku Databricks, ke kterému má agent přístup, oprávnění pro přístup k prostředkům Databricks. Pokud chcete získat přístup k registru výzvy, udělte oprávnění
CREATE FUNCTION,EXECUTE, aMANAGEke schématu Unity Catalog, které se používá pro ukládání výzev. - Vytvořte PAT pro služební účet.
Osobní účet:
Bezpečně uložte PAT vytvořením tajemství Databricks pro PAT.
Konfigurace ověřování PAT v kódu agenta:
import os # Configure PAT authentication for Prompt Registry access # Replace with your actual secret scope and key names secret_scope_name = "your-secret-scope" secret_key_name = "your-pat-key" os.environ["DATABRICKS_HOST"] = "https://<your-workspace-url>" os.environ["DATABRICKS_TOKEN"] = dbutils.secrets.get(scope=secret_scope_name, key=secret_key_name) # Validate configuration assert os.environ["DATABRICKS_HOST"], "DATABRICKS_HOST must be set" assert os.environ["DATABRICKS_TOKEN"], "DATABRICKS_TOKEN must be set"Při nasazování agenta pomocí
agents.deploy()zahrňte PAT jako proměnnou prostředí:agents.deploy( UC_MODEL_NAME, uc_registered_model_info.version, environment_vars={ "DATABRICKS_HOST": "https://<your-workspace-url>", "DATABRICKS_TOKEN": f"{{{{secrets/{secret_scope_name}/{secret_key_name}}}}}" }, )