Gözetmen API'sini (Beta) kullanarak özel bir aracı oluşturma

Important

Bu özellik Beta sürümündedir. Hesap yöneticileri Bu özelliğe erişimi Önizlemeler sayfasından denetleyebilir. Bkz. Azure Databricks önizlemelerini yönetme.

Aracı döngüsünü kendi kodunuzda yönetmek yerine düzenleme için Supervisor API (Beta) kullanan bir Azure Databricks Apps aracısı oluşturabilirsiniz. Sonuç, özel bir aracı oluşturmayla aynı: sohbet kullanıcı arabirimi, uç nokta ve kimlik doğrulaması içeren dağıtılmış bir uygulama /invocations. Fark, Azure Databricks aracı döngüsünü sizin için çalıştırmasıdır. agent.py tek bir API çağrısı yapar ve Azure Databricks araç seçimi, yürütme ve yanıt sentezini işler.

Gözetmen API'si desteklenen temel modellerden herhangi biriyle çalışır. model Araç tanımlarınıza veya işleyici mantığınıza dokunmadan sağlayıcılar arasında geçiş yapmak için alanı değiştirin.

Gözetmen API'sinin ne zaman kullanılacağı

Aracınız yalnızca Azure Databricks barındırılan araçları kullandığında ve araç çağrıları arasında özel mantığa ihtiyaç duymadığında Gözetmen API'si iyi çalışır. Ajanınız aşağıdakilerden birini gerektiriyorsa bunun yerine özel bir ajan döngüsü kullanın:

  • İstemci tarafı işlev araçları (Gözetmen API'si barındırılan ve istemci tarafı araçlarını tek bir istekte karıştıramaz)
  • Agent Bricks Bilgi Yardımcısı dışındaki diğer uç noktaları
  • Özel almacılar, özel girişler/çıkışlar veya ayrıntılı akış denetimi
  • Koşullu dallanma veya durum yönetimi gibi araç çağrıları arasında özel Python mantığı
  • Gibi çıkarım parametreleri üzerinde denetim temperature

Tam API başvurusu ve desteklenen parametreler için bkz . Gözetmen API'si (Beta).

Gereksinimler

Gözetmen API'sini kullanarak özel aracı oluşturma

Önerilen başlangıç noktası, en son Databricks uygulama şablonundan yeni bir uygulama oluşturmaktır. En son şablonlar, yapay zeka kodlama yardımcıları için yerleşik use-supervisor-api bir becerinin yanı add-tools sıra barındırılan araçlar ekleme becerisini içerir.

Şablondan yeni bir uygulama oluşturmak için bkz. Yapay Zeka Ajanı oluşturma ve Databricks uygulamalarında dağıtma.

Uygulamanız en son şablondan ayarlandıktan sonra projeyi yapay zeka kodlama yardımcınızda açın ve şunu çalıştırın:

Use the Supervisor API skill to update this agent to use the Databricks Supervisor API.

Beceri, c0 öğenizi barındırılan c1 araçlarla çağırmak üzere günceller ve el ile gerçekleştirilen aracı döngüsünün yerini alır. Ayrıca databricks-openai bağımlılığını ekler ve beta sınırlamalarına dikkat çeker.

Sonuç, sohbet kullanıcı arayüzü, kimlik doğrulaması ve bir /invocations uç nokta içeren aynı dağıtılan Uygulama ancak daha basit bir aracı koduyla. Tam dağıtım iş akışı için (Uygulamalara dağıtın, araçlar ekleyin, değerlendirin) bkz. Bir yapay zeka aracısı yazma ve Databricks Uygulamalarında dağıtma.

Desteklenen araçlar ve parametreler

Desteklenen araç türlerinin, istek parametrelerinin ve kod örneklerinin tam listesi için bkz . Gözetmen API'si (Beta).

İçinde databricks.yml her eklediğiniz araç için ilgili kaynak iznini de verin. Örnekler için add-tools içindeki .claude/skills/ becerisine bakın.

Barındırılan araçlar için yetkilendirme

Gözetmen API'si aracı döngüsünü çalıştırdığında, uygulamanın kimliğini veya istekte bulunan kullanıcının kimliğini kullanarak barındırılan araçları yürütür. Uygulamanın tüm kullanıcılarının araçlarınıza aynı erişimi mi paylaşacaklarını yoksa her kullanıcının yalnızca kendi izinlerinin izin verdikleri erişime mi erişmesi gerektiğini seçin.

  • Uygulama yetkilendirmesi (varsayılan): Araçlar, uygulamanın hizmet sorumlusu olarak çalışır. Aracının kullandığı her araç için hizmet sorumlusu izni verin. Bkz. Uygulama yetkilendirme.
  • Kullanıcı yetkilendirmesi: Araçlar isteği gönderen kullanıcı olarak çalışır, bu nedenle Unity Kataloğu izinleri, satır filtreleri ve sütun maskeleri kullanıcı başına uygulanır. Aşağıdaki bölüme bakın.

Araçları istekte bulunan kullanıcı olarak çalıştırma

Important

Kullanıcı yetkilendirmesi Genel Önizleme aşamasındadır. Uygulamanıza kapsam ekleyebilmeniz için önce çalışma alanı yöneticinizin bunu etkinleştirmesi gerekir. Bkz. Uygulamaya kapsam ekleme.

İstekte bulunan kullanıcı adına barındırılan araçları çalıştırmak için, kullanıcının belirtecini istemciye iletin DatabricksOpenAI ve araçlarınıza gereken kullanıcı yetkilendirme kapsamlarını ekleyin.

  1. Uygulamanızın ihtiyaç duyduğu kullanıcı yetkilendirme kapsamlarını ekleyin. ai-gateway tüm Gözetmen API erişimi için gereklidir. Ajanın kullandığı her araç türü için araç bazında kapsam ekleyin:

    Araç türü Gerekli kapsam
    Tüm araçlar ai-gateway
    genie_space genie
    uc_function mcp.functions
    knowledge_assistant model-serving
    uc_connection catalog.connections

    Araç app türü kullanıcı yetkilendirmesi ile desteklenmez. Bir Uygulama uç noktasını araç olarak çağırmak için bunun yerine uygulama yetkilendirmesini kullanın. Çalışma alanı kullanıcı arabirimi veya Bildirim temelli Otomasyon Paketleri aracılığıyla kapsam ekleme hakkında bilgi için bkz. Kullanıcı yetkilendirmesi.

  2. İşleyicinizde, agent.py öğesine bir kullanıcı çalışma alanı istemcisi iletin. Bu, Gözetmen'e özgü tek kablolamadır: Bir kaynağı doğrudan kullanıcı istemcisiyle çağırmak yerine aracı döngüsünü çalıştıran istemciye teslim edin.

    from databricks_openai import DatabricksOpenAI
from agent_server.utils import get_user_workspace_client

# Inside your invoke or stream handler, not at app startup
client = DatabricksOpenAI(
  workspace_client=get_user_workspace_client(),
  use_ai_gateway=True,
)

    get_user_workspace_client() yalnızca sorgu zamanında doldurulan istek üst bilgilerinden iletilen kullanıcı belirtecini okur. Bunu invoke ve stream işleyicileri içinde çağırın; asla __init__ içinde veya uygulama başlangıcında çağırmayın. İletilen belirteç eksikse, sonuçta elde edilen istemcinin kimliği istekte bulunan kullanıcı olarak doğrulanmamıştır. Aracının uygulamanın hizmet sorumlusu yerine çağıran olarak çalıştığını doğrulamak için bkz. Kullanıcı yetkilendirmesi.

  3. Aracıyı çalıştıran her kullanıcıya, her araç için gerekli izni verin; örneğin, bir Genie Agent üzerinde CAN_RUN veya bir bilgi yardımcısı uç noktasında CAN_QUERY.

Ek kaynaklar

  • Last updated on