Yapay zeka aracıları için kimlik doğrulaması (Model Hizmet)

Yapay zeka aracılarının görevleri tamamlamak için genellikle diğer kaynaklarda kimlik doğrulaması gerçekleştirmesi gerekir. Örneğin, dağıtıma alınmış bir aracının, yapılandırılmamış verileri sorgulamak için bir AI Search dizinine veya dinamik istemleri yüklemek için İstem Kayıt Defteri'ne erişmesi gerekebilir.

Bu sayfa, Özel Aracılar kullanarak aracı geliştirirken ve dağıtırken kullanılabilen kimlik doğrulama yöntemlerini kapsar.

Kimlik doğrulama yöntemleri

Aşağıdaki tablo, kullanılabilir kimlik doğrulama yöntemlerini karşılaştırır. Bu yaklaşımlardan herhangi birini karıştırabilir ve eşleştirebilirsiniz:

Kaynağınız için doğru kimlik doğrulama yöntemini seçin

Her kaynak için doğru kimlik doğrulama yöntemini seçmek için bu akış çizelgesini kullanın. Gerektiğinde yöntemleri birleştirebilirsiniz ve bir aracı, kullanım örneğine bağlı olarak her kaynak için farklı bir yöntem kullanabilir.

1. Kullanıcı başına erişim denetimi veya kullanıcı öznitelikli denetim gerekli mi?

   • Evet → Kullanıcı adına kimlik doğrulaması kullanma
   • → Yok 2. adıma devam edin

2. Tüm kaynaklar otomatik kimlik doğrulamayı destekliyor mu?

   • Evet → Otomatik kimlik doğrulaması geçişi kullan (önerilir)
   • Hayır → El ile kimlik doğrulaması kullan

Databricks MCP sunucularında kimlik doğrulaması

Databricks MCP sunucularında kimlik doğrulaması yapmak için, aracınızın günlüğe kaydetme zamanında ihtiyaç duyduğu tüm kaynakları belirtin.

Örneğin, aracınız aşağıda listelenen MCP sunucu URL’lerini kullanıyorsa, prod.customer_support ve prod.billing şemalarında tüm AI Search dizinlerini belirtmeniz gerekir. Tüm Unity Kataloğu işlevlerini prod.billing içinde belirtmelisiniz.

• https://<your-workspace-hostname>/api/2.0/mcp/ai-search/prod/customer_support
• https://<your-workspace-hostname>/api/2.0/mcp/ai-search/prod/billing
• https://<your-workspace-hostname>/api/2.0/mcp/functions/prod/billing

Yönetilen MCP sunucuları için tüm bağımlı kaynakları tanımlama işlemini basitleştirmek için, yönetilen MCP sunucusunun ihtiyaç duyduğu kaynakları almak için PyPI paketini databricks-mcp kullanındatabricks_mcp.DatabricksMCPClient().get_databricks_resources(<server_url>).

Aracınız Databricks uygulamasında barındırılan özel bir MCP sunucusunu sorgularsa, modelinizi günlüğe kaydederken sunucuyu açıkça kaynak olarak ekleyerek yetkilendirmeyi yapılandırabilirsiniz.

Otomatik kimlik doğrulama geçişi

Otomatik kimlik doğrulama geçişi, Databricks tarafından yönetilen kaynaklara erişmenin en basit yoludur. Aracı günlüğe kaydederken kaynak bağımlılıklarını belirtin; Databricks, aracı dağıtıldığında kısa ömürlü kimlik bilgilerini otomatik olarak düzenler, yeniler ve yönetir.

Bu kimlik doğrulama davranışı, Databricks gösterge panoları için "Run as owner" davranışına benzer bir şekilde çalışır. Unity Kataloğu tabloları gibi aşağı akış kaynaklarına yalnızca aracının ihtiyaç duyduğu kaynaklara en az ayrıcalıklı erişime sahip bir hizmet sorumlusunun kimlik bilgileri kullanılarak erişilir.

Otomatik kimlik doğrulama geçişi nasıl çalışır?

Otomatik kimlik doğrulama geçişi kullanılarak bir aracı bir uç noktanın arkasında sunulduğunda Databricks aşağıdaki adımları gerçekleştirir:

1. Yetki doğrulaması: Databricks, uç nokta yapıcısının ajan günlüğü sırasında belirtilen tüm bağımlılıklara erişebildiğini doğrular.

2. Hizmet sorumlusu oluşturma ve verme: Aracı modeli sürümü için bir hizmet sorumlusu oluşturulur ve aracı kaynaklarına otomatik olarak okuma erişimi verilir.

   Note

   Sistem tarafından oluşturulan hizmet sorumlusu API veya kullanıcı arabirimi listelerinde görünmez. Aracı model sürümü uç noktadan kaldırılırsa, hizmet ilkesi de silinir.

3. Kimlik bilgisi sağlama ve döndürme: Hizmet sorumlusu için kısa süreli kimlik bilgileri ( M2M OAuth belirteci) uç noktaya eklenir ve aracı kodunun Databricks kaynaklarına erişmesine olanak sağlar. Databricks ayrıca yetkilendirme bilgilerini belirli aralıklarla güncelleyerek aracınızın bağımlı kaynaklara güvenli erişimini sürdürmesini sağlar.

Otomatik kimlik doğrulaması geçişi için desteklenen kaynaklar

Aşağıdaki tabloda, otomatik kimlik doğrulama geçişini destekleyen Databricks kaynakları ve aracı dağıtılırken uç nokta oluşturucusunun sahip olması gereken izinler listelenir.

Otomatik kimlik doğrulama aktarımını uygulama

Otomatik kimlik doğrulama geçişini etkinleştirmek için aracıyı günlüğe kaydederken bağımlı kaynakları belirtin. resources API'sinin log_model() parametresini kullanın.

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"),
    ]
  )

Kullanıcı adına kimlik doğrulaması

Kullanıcı adına (OBO) kimlik doğrulaması, bir aracının sorguyu çalıştıran Databricks kullanıcısı olarak davranmasına olanak tanır. Bu, şu bilgileri sağlar:

• Hassas verilere kullanıcı başına erişim
• Unity Kataloğu tarafından uygulanan ince ayrıntılı veri denetimleri
• Güvenlik belirteçleri yalnızca aracınızın bildirmiş olduğu API'lerle kısıtlanır ("kapsam kapsamına alınır") ve kötüye kullanım riskini azaltır

Gereksinimler

• Kullanıcı adına kimlik doğrulaması için MLflow 2.22.1 ve üzeri gerekir.
• Kullanıcı adına kimlik doğrulaması varsayılan olarak devre dışıdır ve çalışma alanı yöneticisi tarafından etkinleştirilmesi gerekir. Bu özelliği etkinleştirmeden önce güvenlikle ilgili dikkat edilmesi gereken noktaları gözden geçirin.

OBO tarafından desteklenen kaynaklar

Model Sunma uç noktalarında, OBO kimlik doğrulamasına sahip aracılar yalnızca aşağıdaki tabloda listelenen Databricks kaynaklarına erişebilir. Unity Katalog Birimleri (dosya yükleme/indirme) gibi burada listelenmeyen kaynaklar Model Sunma'da OBO için desteklenmez.

OBO kimlik doğrulamayı uygulama

Kullanıcı adına kimlik doğrulamasını etkinleştirmek için aşağıdaki adımları tamamlayın:

1. Kaynaklara son kullanıcı adına erişildiğini belirtmek için SDK çağrılarını güncelleştirin.
2. Kullanıcı kimliği yalnızca çalışma zamanında bilindiğinden, OBO erişimini predict işlevinin içinde ve __init__'in içinde olmadan başlatmak için aracı kodunu güncelleyin.
3. Aracıyı dağıtım için günlüğe kaydedirken, aracının gerektirdiği Databricks REST API kapsamlarını bildirin.

Aşağıdaki kod parçacıklarında farklı Databricks kaynaklarına kullanıcı adına erişimin nasıl yapılandırılacağı gösterilmektedir. Araçları başlatırken, başlatma işlemini bir try-except blok içinde sararak izin hatalarını düzgün bir şekilde yönetin.

Yapay Zekâ Arama Getirme Aracı

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

AI Arama İstemcisi

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
  )

Model Sunum Uç Noktası

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

UC Bağlantıları

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"},
)

Genie Ajanları (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")

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

Aracıyı predict işlevinde başlatma

Kullanıcının kimliği yalnızca sorgu zamanında bilindiğinden, OBO kaynaklarına predict veya predict_stream içinde erişmeniz gerekir, aracının __init__ yönteminde değil. Bu, kaynakların çağrılar arasında yalıtılmasını sağlar.

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

Aracın günlük kaydını yaparken REST API kapsamlarını tanımlayın

OBO aracınızı dağıtım için kaydettiğinizde, aracınızın kullanıcı adına çağıracağı Databricks REST API kapsamlarını listelemeniz gerekir. Bu, aracının en az ayrıcalık ilkesine uygun olmasını sağlar: Belirteçler yalnızca aracınızın gerektirdiği API'lerle sınırlandırılır ve yetkisiz eylemler veya belirtecin kötüye kullanımı olasılığını azaltır.

Model Sunma uç noktaları üzerinde yalnızca yukarıda listelenen OBO tarafından desteklenen kaynaklara karşılık gelen kapsamları kullanabilirsiniz.

Kullanıcı adına kimlik doğrulamasını etkinleştirmek için bir MLflow AuthPolicylog_model() öğesine geçirin.

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

OpenAI istemcileri için OBO kimlik doğrulaması

OpenAI istemcisini kullanan aracılar için Databricks SDK'sını kullanarak dağıtım sırasında otomatik olarak kimlik doğrulaması yapın. Databricks SDK'sı, kimlik doğrulamasının otomatik olarak yapılandırıldığı get_open_ai_client()OpenAI istemcisini oluşturmak için bir sarmalayıcıya sahiptir:

% pip install databricks-sdk[openai]

from databricks.sdk import WorkspaceClient
def openai_client(self):
  w = WorkspaceClient()
  return w.serving_endpoints.get_open_ai_client()

Ardından dağıtım zamanında otomatik olarak kimlik doğrulaması yapmak için model resources sunma uç noktasını belirtin.

OBO güvenlik konuları

Aracılarla kullanıcı adına kimlik doğrulamasını etkinleştirmeden önce aşağıdaki güvenlik konularını göz önünde bulundurun.

Genişletilmiş kaynak erişimi: Aracılar, kullanıcılar adına hassas kaynaklara erişebilir. Kapsamlar API'leri kısıtlasa da uç noktalar aracınızın açıkça istediğinden daha fazla eyleme izin verebilir. Örneğin, model-serving API kapsamı, bir acentenin kullanıcı adına bir servis uç noktasını çalıştırmasına izin verir. Ancak, sunum uç noktası özgün aracının kullanma yetkisi olmayan ek API kapsamlarına erişebilir.

OBO örnek not defterleri

Aşağıdaki not defteri, kullanıcı adına yetkilendirmeyi kullanarak AI Search ile nasıl aracı oluşturacağınızı gösterir.

Yapay Zeka Arama ile Kullanıcı Yetkilendirmesi Adına

Dizüstü bilgisayar al

Aşağıdaki not defterinde, kullanıcı adına yetkilendirme kullanarak SQL Ambarı'nda SQL yürütmeyi destekleyen bir aracı oluşturma işlemi gösterilmektedir. Bu, aracının kullanıcı kimlik bilgilerini kullanarak Unity Kataloğu işlevlerini güvenli bir şekilde çağırmasını sağlar.

SQL Yürütme ile Kullanıcı Yetkilendirmesi Adına

Dizüstü bilgisayar al

El ile kimlik doğrulaması

El ile kimlik doğrulaması, aracı dağıtımı sırasında kimlik bilgilerinin açıkça belirtilmesine olanak tanır. Bu yöntem en fazla esnekliğe sahiptir ancak daha fazla kurulum ve devam eden kimlik bilgileri yönetimi gerektirir. Şu durumlarda bu yöntemi kullanın:

• Bağımlı kaynak otomatik kimlik doğrulama geçişini desteklemiyor
• Ajanın, ajan dağıtıcısının kimlik bilgileri dışında başka kimlik bilgilerini kullanması gerekir.
• Aracı, Databricks dışındaki dış kaynaklara veya API'lere erişir
• Dağıtılan aracı komut istemi kayıt defterine erişir

OAuth kimlik doğrulaması (önerilir)

Otomatik belirteç yenileme özelliklerine sahip hizmet sorumluları için güvenli, belirteç tabanlı kimlik doğrulamasına sahip olduğundan OAuth, el ile kimlik doğrulaması için önerilen yaklaşımdır:

1. Bir hizmet sorumlusu oluşturun ve OAuth kimlik bilgileri oluşturun.

2. Hizmet sorumlusuna, aracının Databricks kaynaklarına erişim ayrıcalıklarına sahip olduğu herhangi bir Databricks kaynağına izin verin. İstem kayıt defterine erişmek için, istemleri depolamak amacıyla Unity Katalogu şemasında CREATE FUNCTION, EXECUTE ve MANAGE izinlerini verin.

3. OAuth kimlik bilgileri için databricks gizli dizileri oluşturun.

4. Aracı kodunda OAuth kimlik bilgilerini yapılandırın:

   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)
   

5. Çalışma alanına bağlanmak için gizli bilgileri kullanın.

   w = WorkspaceClient(
     host=os.environ["DATABRICKS_HOST"],
     client_id=os.environ["DATABRICKS_CLIENT_ID"],
     client_secret = os.environ["DATABRICKS_CLIENT_SECRET"]
   )
   

6. ile agents.deploy()dağıtım yaparken ortam değişkenleri olarak OAuth kimlik bilgilerini ekleyin:

   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}}}}}"
       },
   )
   

PAT kimlik doğrulaması

Kişisel Erişim Belirteci (PAT) kimlik doğrulaması geliştirme ve test ortamları için daha basit bir kurulum sağlar, ancak daha fazla el ile kimlik bilgisi yönetimi gerektirir:

1. Hizmet sorumlusu veya kişisel hesap kullanarak PAT alın:

   Hizmet sorumlusu (güvenlik için önerilir):

   1. hizmet sorumlusu oluşturma.
   2. Hizmet sorumlusuna, aracının Databricks kaynaklarına erişim ayrıcalıklarına sahip olduğu herhangi bir Databricks kaynağına izin verin. İstem kayıt defterine erişmek için, istemleri depolamak için kullanılan Unity Kataloğu şemasında, CREATE FUNCTION, EXECUTE ve MANAGE izinlerini verin.
   3. Hizmet sorumlusu için bir PAT oluşturun.

   Kişisel hesap:

   1. Kişisel bir hesap için PAT oluşturun.

2. PAT için bir Databricks gizli dizisi oluşturarak PAT'yi güvenli bir şekilde depolayın.

3. Aracı kodunda PAT kimlik doğrulamasını yapılandırın:

   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"
   

4. agents.deploy() kullanarak aracı deploy ederken, PAT'yi bir ortam değişkeni olarak kullanın.

   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}}}}}"
       },
   )