Yapay zeka aracıları için kimlik doğrulaması

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ılan bir aracı yapılandırılmamış verileri sorgulamak için bir Yapay Zeka Arama dizinine, temel modeli çağırmak için bir sunum uç noktasına veya özel mantık yürütmek için Unity Kataloğu işlevlerine erişmesi gerekebilir.

Bu sayfa, Databricks Uygulamalarında dağıtılan aracılar için kimlik doğrulama yöntemlerini kapsar. Model Sunma uç noktalarına dağıtılan aracılar için bkz. Yapay zeka aracıları için kimlik doğrulaması (Model Sunma).

Databricks Apps aracılar için iki kimlik doğrulama yöntemi sağlar. Her yöntem farklı kullanım örnekleri sunar:

Her iki yöntemi de tek bir aracıda birleştirebilirsiniz. Örneğin, kullanıcıya özgü tabloları sorgulamak için kullanıcı yetkilendirmesini kullanırken paylaşılan bir AI Arama dizinine erişmek için uygulama yetkilendirmesini kullanın.

Çalışma alanı kullanıcı arabirimi veya Bildirim temelli Otomasyon Paketleri ile kimlik doğrulamasını yapılandırma

Tüm kimlik doğrulama ayarlarını iki şekilde yapılandırabilirsiniz:

• Çalışma alanı kullanıcı arabirimi: Uygulamayı düzenleyin ve Yapılandır adımından kaynakları ve kapsamları yönetin. Çalışma alanı içinde tek bir uygulama üzerinde yineleme yaparken önerilir.
• Beyan Edici Otomasyon Paketleri: Bir databricks.yml dosyasındaki kaynakları, kapsamları ve ortam değişkenlerini beyan edin ve databricks bundle deploy ile dağıtın. Git tabanlı sürüm oluşturma, CI/CD veya aynı aracıyı çalışma alanları arasında göndermek istediğinizde önerilir. Tüm aracı şablonları ile databricks.ymlbirlikte sunulur.

Her iki yol da aynı çalışma zamanı yapılandırmasını oluşturur. Bu sayfanın geri kalanında her yönerge her iki biçimde de gösterilir, böylece birini seçebilir ve projenizde tutarlı kalabilirsiniz.

Her iki yolla da uygulamaya kaynak eklemek için hem kaynak hem de uygulama üzerinde izniniz olmalıdır Can Manage .

Tam paket referansı için bkz. uygulama kaynağı ve app.resources. Uçtan uca paket kılavuzu için bkz. Bildirim temelli Otomasyon Paketlerini kullanarak Databricks uygulamalarını yönetme.

Uygulama yetkilendirme

Varsayılan olarak, Databricks Apps uygulama yetkilendirmesini kullanarak kimlik doğrulaması yapar. Databricks, uygulamayı oluşturduğunuzda otomatik olarak bir hizmet sorumlusu oluşturur ve uygulamanın kimliği olarak görev yapar.

Uygulamayla etkileşim kuran tüm kullanıcılar hizmet sorumlusu için tanımlanan izinleri paylaşır. Bu model, tüm kullanıcıların aynı verileri görmesini istediğinizde veya uygulama kullanıcıya özgü erişim denetimlerine bağlı olmayan paylaşılan işlemler gerçekleştirdiğinde iyi çalışır.

Uygulama yetkilendirme hakkında ayrıntılı bilgi için bkz. Uygulama yetkilendirme.

MLflow denemesine izin verme

Etmeninizin izlemeleri ve değerlendirme sonuçlarını günlüğe kaydetmek için bir MLflow deneyine erişmesi gerekir. Deneme üzerinde hizmet temsilcisine Can Edit izin verin.

Çalışma Alanı Kullanıcı Arabirimi

1. Uygulama giriş sayfanızda Düzenle'ye tıklayın.
2. Yapılandır adımına gidin.
3. Uygulama kaynakları bölümünde, izinli Can Edit MLflow deneme kaynağını ekleyin.

Bkz. Databricks uygulamasına MLflow deneme kaynağı ekleme.

Bildirim temelli Otomasyon Paketleri

1. Denemeyi içindeki uygulamanızın resources listesi altında bildirin databricks.yml. Kaynağa name atadığınız öğesine daha sonra ortam değişkenlerini bağladığınızda başvurulur.

   resources:
     apps:
       my_agent:
         name: 'my-agent'
         source_code_path: ./
         resources:
           - name: 'experiment'
             experiment:
               experiment_id: '<experiment-id>'
               permission: 'CAN_EDIT'
   

2. Paketi yeniden dağıtın:

   databricks bundle deploy
   databricks bundle run my_agent
   

Bkz. tüm alanlar için app.resources.experiment .

Diğer Databricks kaynaklarına izin verme

Ajanınız Genie ajanları, AI Search dizinleri veya SQL ambarları gibi diğer Databricks kaynaklarını kullanıyorsa, hizmet sorumlusuna bunların her biri için 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.

Unity Kataloğu kaynaklarına erişim izni verirken, aşağı akışa bağımlı tüm kaynaklara da izin vermelisiniz. Örneğin, bir Genie Aracısı'na erişim izni verirseniz, temel alınan tablolara, SQL ambarlarına ve Unity Kataloğu işlevlerine de erişim vermelisiniz.

Çalışma Alanı Kullanıcı Arabirimi

Databricks çalışma alanında uygulamayı oluştururken veya düzenlerken Uygulama kaynakları bölümü aracılığıyla uygulamaya kaynak ekleyin.

1. Uygulama giriş sayfanızda Düzenle'ye tıklayın.
2. Yapılandır adımına gidin.
3. Uygulama kaynakları'nda, aracının kullandığı her kaynak için + Kaynak ekle'ye tıklayın ve izni ayarlayın.

Desteklenen kaynakların ve ekran görüntülerinin tam listesi için bkz. Databricks uygulamasına kaynak ekleme .

Bildirim temelli Otomasyon Paketleri

1. Uygulamanızın resources altındaki databricks.yml listesinde aracının kullandığı her kaynağı bildirin. Aşağıdaki örnek, MLflow deneyi, servis uç noktası, Genie Aracısı, SQL veri ambarı, AI Search indeksi, Unity Kataloğu işlevi ve Lakebase örneği kullanan bir aracıyı göstermektedir. Her kaynak, aracının çözümlenen tanımlayıcıyı çalışma zamanında alabilmesi için name üzerinden config.env ile referans gösterilir.

   bundle:
     name: my_agent
   
   resources:
     apps:
       my_agent:
         name: 'my-agent'
         description: 'Custom agent deployed on Databricks Apps'
         source_code_path: ./
         config:
           command: ['uv', 'run', 'start-app']
           env:
             - name: MLFLOW_EXPERIMENT_ID
               value_from: 'experiment'
             - name: LAKEBASE_INSTANCE_NAME
               value_from: 'database'
   
         resources:
           - name: 'experiment'
             experiment:
               experiment_id: '<experiment-id>'
               permission: 'CAN_EDIT'
   
           - name: 'llm'
             serving_endpoint:
               name: 'databricks-claude-sonnet-4-5'
               permission: 'CAN_QUERY'
   
           - name: 'sales-genie'
             genie_space:
               space_id: '<genie-space-id>'
               permission: 'CAN_RUN'
   
           - name: 'warehouse'
             sql_warehouse:
               id: '<warehouse-id>'
               permission: 'CAN_USE'
   
           - name: 'docs-index'
             uc_securable:
               securable_full_name: 'main.docs.chunks_index'
               securable_type: 'TABLE'
               permission: 'SELECT'
   
           - name: 'lookup-function'
             uc_securable:
               securable_full_name: 'main.tools.order_lookup'
               securable_type: 'FUNCTION'
               permission: 'EXECUTE'
   
           - name: 'database'
             database:
               instance_name: '<lakebase-instance-name>'
               database_name: 'databricks_postgres'
               permission: 'CAN_CONNECT_AND_CREATE'
   
   targets:
     dev:
       mode: development
       default: true
   

   Important

   value_from içindeki her config.env değerin, name listesindeki bir resources alanla eşleşmesi gerekir. Uyuşmazlıklar, ortam değişkeninin dağıtılan uygulamada None olarak çözülmesine neden olur.

2. Paketi dağıtın ve başlatın:

   databricks bundle validate
   databricks bundle deploy
   databricks bundle run my_agent
   

   bundle deploy kaynağı karşıya yükler ve kaynakları yapılandırır. bundle run uygulamayı en son kaynakla başlatır veya yeniden başlatır. Bağımsız değişken bundle run, resources.apps altındaki YAML anahtarıdır (burada my_agent), dağıtılan uygulamanın name alanı değil.

Her kaynak alt türünün tam şeması için bkz. app.resources.

Aşağıdaki tabloda yukarıdaki örneklerde kullanılan en düşük izinler ve her kaynak türü için eşdeğer Bildirim temelli Otomasyon Paketleri değeri listelenmiştir:

En düşük ayrıcalık ilkesini izleyin. Hizmet sorumlusuna yalnızca aracının ihtiyaç duyduğu izinleri verin ve uygulama başına ayrılmış bir hizmet sorumlusu kullanın. Tam liste için bkz . En iyi güvenlik yöntemleri.

Kullanıcı yetkilendirmesi

Kullanıcı yetkilendirmesi, bir aracının isteği yapan kullanıcının kimliğiyle hareket etmesini sağlar. 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
• Kullanıcıya özgü denetim izleri
• Satır düzeyi filtrelerin ve sütun maskelerinin otomatik olarak uygulanması

Aracınızın, uygulamanın hizmet sorumlusu yerine istekte bulunan kullanıcının kimliğini kullanarak kaynaklara erişmesi gerektiğinde kullanıcı yetkilendirmesini kullanın.

Kullanıcı yetkilendirmesi nasıl çalışır?

Acentanız için kullanıcı yetkilendirmesini yapılandırdığınızda:

1. Uygulamanıza API kapsamları ekleme: Uygulamanın kullanıcılar adına erişebileceği Databricks API'lerini tanımlayın. Bkz. Uygulamaya kapsam ekleme.
2. Kullanıcı kimlik bilgileri kapsam dahilindedir: Databricks kullanıcının kimlik bilgilerini alır ve bunları yalnızca tanımladığınız API kapsamlarıyla kısıtlar.
3. Belirteç iletme: Daraltılmış kapsam belirteci, x-forwarded-access-token HTTP üst bilgisi aracılığıyla uygulamanız için kullanılabilir hale getirilir.
4. MLflow AgentServer belirteci depolar: Aracı Sunucusu, aracı kodunda uygun erişim için istek başına bu belirteci otomatik olarak depolar.

Uygulamanızı oluştururken veya düzenlerken Veya API'yi kullanarak program aracılığıyla Databricks Uygulamaları kullanıcı arabirimine kapsamlar ekleyerek kullanıcı yetkilendirmesini yapılandırın. Ayrıntılı yönergeler için bkz. Uygulamaya kapsam ekleme .

Kullanıcı yetkilendirmesine sahip aracılar aşağıdaki Databricks kaynaklarına erişebilir:

• SQL Ambarı
• Genie Ajanı
• Dosyalar ve dizinler
• Model Sunum Uç Noktası
• AI Arama Dizini
• Unity Kataloğu Bağlantıları
• Unity Katalog Tabloları

Kullanıcı yetkilendirmesi uygulama

Kullanıcı yetkilendirmesini uygulamak için uygulamanıza yetkilendirme kapsamları eklemeniz gerekir. Kapsamlar, uygulamanın kullanıcı adına yapabileceklerini kısıtlar. Kullanılabilir kapsamların ve kapsam semantiğinin listesi için bkz. Kapsam tabanlı güvenlik ve ayrıcalık yükseltme.

Çalışma Alanı Kullanıcı Arabirimi

1. Databricks kullanıcı arabiriminde uygulamanızın Yetkilendirme ayarlarına gidin.
2. Kullanıcı yetkilendirmesi'nin altında + Kapsam ekle'ye tıklayın ve uygulamanın kullanıcı adına kaynaklara erişmesi için gereken kapsamları seçin.
3. Değişiklikleri kaydedin ve uygulamayı yeniden başlatın.

Bildirim temelli Otomasyon Paketleri

1. user_api_scopes üzerindeki databricks.yml kapsamlarını uygulama kaynağı altında bildirin.

   resources:
     apps:
       my_agent:
         name: 'my-agent'
         source_code_path: ./
         user_api_scopes:
           - sql
           - genie
           - model-serving
         resources:
           - name: 'experiment'
             experiment:
               experiment_id: '<experiment-id>'
               permission: 'CAN_EDIT'
   

2. Paketi yeniden dağıtın ve uygulamayı yeniden başlatın:

   databricks bundle deploy
   databricks bundle run my_agent
   

   Note

   Çalışma alanında kullanıcı yetkilendirmesini ilk kez etkinleştirdikten sonra, kapsamları kullanabilmeleri için mevcut uygulamaları yeniden başlatmanız gerekir. Bkz. Uygulamaya kapsam ekleme.

Aracı kodunuzda kullanıcı yetkilendirmesini yapılandırmak için, Bu isteğin üst bilgisini AgentServer'dan alın ve bu kimlik bilgileriyle bir çalışma alanı istemcisi oluşturun.

1. Aracı kodunuzda kimlik doğrulama yardımcı programını içeri aktarın:

   Databricks/app-templates tarafından sağlanan şablonlardan birini kullanıyorsanız, sağlanan yardımcı programı içeri aktarın:

   from databricks_app.utils import get_user_workspace_client
   

   Aksi takdirde, Agent Server araçlarından içeri aktarın.

   from agent_server.utils import get_user_workspace_client
   

   get_user_workspace_client() işlevi, x-forwarded-access-token üst bilgisini yakalamak üzere Aracı Sunucusu'nu kullanır ve bu kullanıcı kimlik bilgileriyle bir çalışma alanı istemcisi oluşturur, kullanıcı, uygulama ve aracı sunucu arasındaki kimlik doğrulamasını yönetir.

2. Çalışma alanı istemcisini uygulama başlatma sırasında değil sorgu zamanında başlatın:

   Important

   get_user_workspace_client() fonksiyonunu invoke ve stream işleyicileri içinde, __init__ veya uygulama başlangıcında çağırmayın. Kullanıcı kimlik bilgileri yalnızca bir kullanıcı istekte bulunduğunda sorgu zamanında kullanılabilir. Uygulama başlatma sırasında başlatma işlemi başarısız olur çünkü henüz kullanıcı bağlamı yoktur.

   # In your agent code (inside invoke or stream handler)
   user_client = get_user_workspace_client()
   
   
   # Use user_client to access Databricks resources with user permissions
   response = user_client.serving_endpoints.query(name="my-endpoint", inputs=inputs)
   

Kapsam ekleme ve kapsam tabanlı güvenliği anlama hakkında eksiksiz bir kılavuz için bkz. Kapsam tabanlı güvenlik ve ayrıcalık yükseltme. Yalnızca aracınızın ihtiyaç duyduğu en düşük kapsamları isteyin ve bir kullanıcı adına yapılan her işlemi kaydedin. Bkz. Kullanıcı yetkilendirmesi için en iyi yöntemler.

Kullanıcı yetkilendirmeyi doğrulama

Kapsamları ekleyip get_user_workspace_client() çağrısını yaptıktan sonra, aracının uygulamanın hizmet sorumlusu olarak değil, çağıran kimliğiyle çalıştığını doğrulayın. İletilen belirteç eksikse, get_user_workspace_client() yükseltmeden hizmet sorumlusuna geri döner, böylece aracı uygulama olarak hareket ederken normal görünümlü bir yanıt döndürebilir. Kontrol etmek için bir whoami aracı ekleyin ve onu kendi kimliğinizle çağırın. Kullanıcı adınızı döndürürse, kullanıcı yetkilendirmesi çalışır.

current_user.me() varsayılan iam.current-user:read kapsam kapsamındadır, bu nedenle bu test için herhangi bir kapsam eklemeniz gerekmez.

from agents import Agent, function_tool
from agent_server.utils import get_user_workspace_client

@function_tool
def whoami() -> str:
    """Returns the identity of the current user."""
    user_wc = get_user_workspace_client()
    return user_wc.current_user.me().user_name

agent = Agent(
    name="my-agent",
    instructions=(
        "When the user asks who they are, call the whoami tool "
        "and return the raw result."
    ),
    model="databricks-claude-sonnet-4-6",
    tools=[whoami],
)

Aracıyı yeniden dağıtın. Bkz. Bir yapay zeka aracısı yazma ve Databricks Uygulamalarında dağıtma.

Çalışma Alanı Kullanıcı Arabirimi

Çalışma Alanı kullanıcı arabirimi testi en hızlı akıl sağlığı denetimidir ve OAuth belirteçleri gerektirmez.

1. Kapsam değişiklikleri hemen geçerli olur, ancak iç önbelleklerin yenilenmesi 5 dakika kadar sürebilir; testten önce bu kadar bekleyin (uygulama yeniden başlatması gerekmez). Uygulama URL'si için tarayıcı tanımlama bilgilerinizi her zaman temizleyin (adımlar için aşağıdaki açılan menüye bakın), aksi takdirde oturum kapsam değişikliğinden önce verilen belirteçleri yeniden kullanır.
2. CAN USE Uygulama üzerinde izniniz olduğunu onaylayın. Bkz . Databricks uygulaması için izinleri yapılandırma.
3. Uygulama URL'sini tarayıcıda açın. İlk ziyarette, istenen kapsamlar için onay istemini kabul edin.
4. Sohbette, Who am I? diye sorun ve ajanın kullanıcı adınızı döndürdüğünü doğrulayın (örneğin, you@your-company.com).

Python

Aracıyı çağırmak için bir CLI profili veya hizmet sorumlusu kimlik bilgileri kullanın. Bkz. sorgu seçenekleri için Azure Databricks üzerinde dağıtılan bir aracıyı sorgulama ve OAuth belirteçlerinin nasıl oluşturulacağını öğrenmek için belirteç tabanlı kimlik doğrulaması kullanarak bir API Databricks uygulamasına bağlanma.

1. Kapsam değişiklikleri hemen geçerlilik kazanır, ancak iç önbelleklerin yenilenmesi 5 dakika kadar sürebilir, bu nedenle test etmeden önce bekleyin (uygulama yeniden başlatma gerekmez).

2. Aracıyı kendi kimliğinizle çağırın:

   from databricks.sdk import WorkspaceClient
   from databricks_openai import DatabricksOpenAI
   
   app_name = "<your-app-name>"
   prompt = [{"role": "user", "content": "Call the whoami tool and return only the raw result."}]
   
   w = WorkspaceClient(profile="<your-profile>")
   client = DatabricksOpenAI(workspace_client=w)
   response = client.responses.create(model=f"apps/{app_name}", input=prompt)
   print(response.output_text)
   

   Çıktı, kullanıcı adınız olmalıdır; örneğin, you@your-company.com.

Araç, kullanıcı adı yerine bir UUID döndürüyorsa, x-forwarded-access-token başlığı araca ulaşmıyor ve ajan, uygulamanın hizmet sorumlusunu kullanmaya geri dönmüş demektir (UUID, uygulamanın hizmet sorumlusu istemci kimliğidir). Tanılamak için aşağıdakilerden her birini onaylayın:

1. Çalışma alanında kullanıcı yetkilendirmesi etkinleştirilir.
2. Uygulamada kapsamlar yapılandırılmıştır.
3. get_user_workspace_client(), uygulama başlangıcında değil, @invoke veya @stream işleyicisi içinde çağrılır.
4. Kod, get_user_workspace_client() kullanır; WorkspaceClient() kullanmaz.

İzleyebileceğiniz birkaç şey:

• whoami aracı üretime geçmeden önce kaldırın. Yalnızca tanılama amaçlıdır ve aracıyı çağırabilen herkese kullanıcı kimliğini açığa çıkarır.
• İkinci bir kullanıcıyla test edin. Tek kullanıcılı bir kontrol, belirtecin iletildiğini doğrular; ikinci bir çağıran ise her isteğin paylaşılan bir yedek yerine kendi kimliğini aldığını doğrular.
• İletilen belirteci hiçbir zaman günlüğe kaydetmeyin. Bkz. Kullanıcı yetkilendirmesi için en iyi yöntemler.
• Belirli bir kapsamı doğrulamak için değerini bu kapsamı gerektiren bir çağrıyla değiştirin current_user.me() . Örneğin, bir ambara yönelik SELECT current_user() ifade, sql kapsamını uçtan uca çalıştırır.

Databricks MCP sunucularında kimlik doğrulaması

Databricks tarafından yönetilen MCP sunucuları, AI Search dizinlerini ve Unity Catalog işlevlerini, https://<workspace>/api/2.0/mcp/ai-search/<catalog>/<schema> ve https://<workspace>/api/2.0/mcp/functions/<catalog>/<schema> biçimindeki URL’ler aracılığıyla araç olarak sunar. Eski /api/2.0/mcp/vector-search/ URL ön eki geriye dönük uyumluluk için çalışmaya devam eder. Kullanılabilir sunucuların ve bunların URL kalıplarının listesi için bkz. Azure Databricks tarafından yönetilen MCP sunucuları.

Kimlik doğrulaması yapmak için aracının hizmet sorumlusuna (veya kullanıcı yetkilendirmesi kullanıyorsa kullanıcıya) bu şemalardaki her aşağı akış kaynağına erişim verin.

Örneğin, aracınız aşağıdaki MCP sunucusu URL'lerini kullanıyorsa:

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

prod.customer_support ve prod.billing içindeki tüm AI Search dizinlerine ve prod.billing içindeki tüm Unity Catalog işlevlerine erişim izni vermelisiniz.

Çalışma Alanı Kullanıcı Arabirimi

Her dizini ve işlevi Uygulama kaynakları'nın altına kaynak olarak ekleyin. Diğer Databricks kaynaklarına izin verme ile aynı adımları izleyin.

Bildirim temelli Otomasyon Paketleri

1. Uygulamanızın uc_securable listesinin altına dizin başına ve işlev başına bir resources giriş ekleyin:

   resources:
     apps:
       my_agent:
         resources:
           - name: 'support-index'
             uc_securable:
               securable_full_name: 'prod.customer_support.tickets_index'
               securable_type: 'TABLE'
               permission: 'SELECT'
   
           - name: 'billing-index'
             uc_securable:
               securable_full_name: 'prod.billing.invoices_index'
               securable_type: 'TABLE'
               permission: 'SELECT'
   
           - name: 'refund-function'
             uc_securable:
               securable_full_name: 'prod.billing.process_refund'
               securable_type: 'FUNCTION'
               permission: 'EXECUTE'
   

2. Paketi yeniden dağıtın:

   databricks bundle deploy
   databricks bundle run my_agent
   

Kendi Databricks uygulamaları (uygulama adları mcp- ile başlayan) olarak barındırılan özel MCP sunucuları henüz paket kaynakları olarak desteklenmemektedir. MCP sunucu uygulamasında aracının hizmet sorumlusunu Can Use ile elle databricks apps update-permissions verin. Ajant şablonları deposundaki custom-mcp-server becerisine bakın.

Sonraki Adımlar

• Bir yapay zeka aracısı yazma ve Databricks Uygulamalarında dağıtma
• Bildirim temelli Otomasyon Paketlerini kullanarak Databricks uygulamalarını yönetme
• Databricks uygulamasında yetkilendirmeyi yapılandırma
• Databricks uygulamasına kaynak ekleme
• uygulama kaynağı referansı