Not
Bu sayfaya erişim yetkilendirme gerektiriyor. Oturum açmayı veya dizinleri değiştirmeyi deneyebilirsiniz.
Bu sayfaya erişim yetkilendirme gerektiriyor. Dizinleri değiştirmeyi deneyebilirsiniz.
Databricks Uygulamalarını kullanarak bir yapay zeka aracısı oluşturun ve dağıtın. Databricks Apps aracı kodu, sunucu yapılandırması ve dağıtım iş akışı üzerinde tam denetim sağlar. Özel sunucu davranışı, git tabanlı sürüm oluşturma veya yerel IDE geliştirmesi gerektiğinde bu yaklaşım idealdir.
Tavsiye
Aracınız yalnızca Azure Databricks barındırılan araçları kullanıyorsa ve araç çağrıları arasında özel mantığa ihtiyacınız yoksa, aracı döngüsünü sizin yerinize Azure Databricks yönetmesine izin vermek için Supervisor API (Beta) kullanabilirsiniz.
Her konuşma aracısı şablonu , ek kurulum gerektirmeden yerleşik bir sohbet kullanıcı arabirimi (yukarıda gösterilmiştir) içerir. Sohbet kullanıcı arabirimi akış yanıtlarını, markdown işlemeyi, Databricks kimlik doğrulamasını ve isteğe bağlı kalıcı sohbet geçmişini destekler.
Gereksinimler
Çalışma alanınızda Databricks Uygulamalarını etkinleştirin. Bkz. Databricks Apps çalışma alanınızı ve geliştirme ortamınızı ayarlama.
Adım 1. Aracı uygulama şablonunu kopyalayın
Databricks uygulama şablonları deposundan önceden oluşturulmuş bir aracı şablonu kullanarak başlayın.
Bu öğretici, aşağıdakileri içeren agent-openai-agents-sdk şablonunu kullanır:
- OpenAI Aracısı SDK'sı kullanılarak oluşturulan bir aracı
- Konuşma REST API'siyle ve etkileşimli sohbet kullanıcı arabirimiyle aracı uygulaması için başlangıç kodu
- MLflow kullanarak aracıyı değerlendirme kodu
Şablonu ayarlamak için aşağıdaki yollardan birini seçin:
Çalışma Alanı Kullanıcı Arabirimi
Çalışma Alanı kullanıcı arabirimini kullanarak uygulama şablonunu yükleyin. Bu işlem uygulamayı yükler ve çalışma alanınızdaki bir işlem kaynağına dağıtır. Daha sonra daha fazla geliştirme için uygulama dosyalarını yerel ortamınızla eşitleyebilirsiniz.
Databricks çalışma alanınızda + Yeni Uygulama'ya> tıklayın.
Agentler>Custom Agent (OpenAI SDK)'ye tıklayın.
Adıyla
openai-agents-templateyeni bir MLflow denemesi oluşturun ve şablonu yüklemek için kurulumun geri kalanını tamamlayın.Uygulamayı oluşturduktan sonra, sohbet kullanıcı arabirimini açmak için uygulama URL'sine tıklayın.
Uygulamayı oluşturduktan sonra, kaynak kodu özelleştirmek için yerel makinenize indirin:
Dosyaları eşitle altındaki ilk komutu kopyalayın
Yerel terminalde kopyalanan komutu çalıştırın.
GitHub'dan kopyalama
Yerel bir ortamdan başlamak için aracı şablonu deposunu kopyalayın ve dizinini agent-openai-agents-sdk açın:
git clone https://github.com/databricks/app-templates.git
cd app-templates/agent-openai-agents-sdk
Adım 2. Aracı uygulamasını anlama
Ajan şablonu, bu temel bileşenlerle üretime hazır bir mimari gösterir. Her bileşen hakkında daha fazla ayrıntı için aşağıdaki bölümleri açın:
Her bileşen hakkında daha fazla ayrıntı için aşağıdaki bölümleri açın:
Yerleşik sohbet kullanıcı arabirimi
Aracı şablonu, sohbet uygulaması şablonunu ön yüzü olarak otomatik olarak getirir ve çalıştırır. Bu sohbet kullanıcı arabirimi aynı Databricks Apps dağıtımında paketlenmiştir ve aracınızla birlikte sunulur, bu nedenle ek kurulum gerekmez.
Sohbet kullanıcı arabirimini doğrudan projenizde özelleştirebilirsiniz. Kalıcı sohbet geçmişini etkinleştirme ve kullanıcı geri bildirim toplama dahil olmak üzere sohbet uygulamasının özellikleri hakkında daha fazla bilgi için bkz. Databricks Apps ile sohbet kullanıcı arabirimi oluşturma ve paylaşma.
MLflow AgentServer
Yerleşik izleme ve gözlemlenebilirlik ile ajan isteklerini işleyen zaman uyumsuz bir FastAPI sunucusu. AgentServer, aracınızı sorgulamak için bir uç nokta sağlar ve istek yönlendirmeyi, günlük kaydını ve hata işlemeyi otomatik olarak yönetir.
ResponsesAgent Arayüz
Databricks, aracılar oluşturmak için MLflow ResponsesAgent önerir.
ResponsesAgent ajanları herhangi bir üçüncü taraf çerçevesiyle oluşturmanıza ve ardından güçlü günlüğe kaydetme, izleme, değerlendirme, dağıtım ve izleme yetenekleri için Databricks AI'nin özellikleriyle entegre etmenize olanak tanır.
Bir ResponsesAgent oluşturmayı öğrenmek için, MLflow belgelerinde yer alan örneklere göz atın - Model Sunma için ResponsesAgent.
ResponsesAgent aşağıdaki avantajları sağlar:
Gelişmiş ajan yetenekleri
- Çok aracılı destek
- Akış çıkışı: Çıkışı daha küçük öbekler halinde akışla aktarın.
- Kapsamlı araç arama ileti geçmişi: Gelişmiş kalite ve konuşma yönetimi için ara araç arama iletileri de dahil olmak üzere birden çok ileti döndürebilirsiniz.
- Araç çağırma onayı desteği
- Uzun süre çalışan araç desteği
Kolaylaştırılmış geliştirme, dağıtım ve izleme
- Herhangi bir çerçeve kullanarak aracılar yazma: Mevcut herhangi bir aracı, kullanıcıya hazır uyumluluk sağlamak amacıyla AI Playground, Aracı Değerlendirmesi ve Aracı İzleme ile arabirim kullanarak sarmalayın.
- Tipli yazma arabirimleri: IDE ve notebook otomatik tamamlama özelliğinden yararlanarak, tipli Python sınıflarını kullanarak aracı kodu yazın.
- Otomatik izleme: MLflow, daha kolay değerlendirme ve görüntüleme için akışlı yanıtları izlemelerde otomatik olarak toplar.
-
OpenAI
Responsesşemasıyla uyumlu: Bkz. OpenAI: Yanıtlar ve ChatCompletion.
OpenAI Aracıları SDK'sı
Şablon, konuşma yönetimi ve araç düzenleme için aracı çerçevesi olarak OpenAI Aracıları SDK'sını kullanır. Herhangi bir çerçeveyi kullanarak aracılar yazabilirsiniz. Anahtar, aracınızı MLflow ResponsesAgent arabirimiyle sarmaktır.
MCP (Model Bağlam Protokolü) sunucuları
Şablon, aracılara araçlara ve veri kaynaklarına erişim vermek için Databricks MCP sunucularına bağlanır. Bkz. Azure Databricks model bağlam protokolü (MCP).
Yapay zeka kodlama asistanlarını kullanarak ajanlar geliştirme
Databricks, ajanlar oluşturmak için Claude, Cursor ve Copilot gibi yapay zeka tabanlı kodlama yardımcılarının kullanılmasını önerir. Yapay zeka yardımcılarının proje yapısını, /.claude/skillskullanılabilir araçları ve AGENTS.md en iyi yöntemleri anlamasına yardımcı olmak için içinde sağlanan aracı becerilerini ve dosyasını kullanın. Aracılar, Databricks Uygulamalarını geliştirmek ve dağıtmak için bu dosyaları otomatik olarak okuyabilir.
Adım 3. Temsilcinize araçlar ekleyin
Aracınıza veritabanlarını sorgulama, belge arama veya dış API'leri MCP sunucularına bağlayarak çağırma gibi özellikler verin. Aracı şablonu varsayılan bir MCP sunucu bağlantısı içerir. Daha fazla araç eklemek için aracı kodunuzda ek MCP sunucuları yapılandırın ve içinde databricks.ymlgerekli izinleri verin.
Desteklenen araç türleri ve kod örnekleri için bkz. Aracıları araçlara bağlama .
Yerel Python işlev araçlarını tanımlama
Dış veri kaynakları veya API'ler gerektirmeyen işlemler için araçları doğrudan aracı kodunuzda tanımlayın. Bu araçlar aracınızla aynı işlemde çalışır ve veri dönüştürmeleri, hesaplamalar veya yardımcı program işlemleri için kullanışlıdır.
OpenAI Aracıları SDK'sı
OpenAI Ajanları SDK'sından @function_tool dekoratörünü kullanın.
from agents import Agent, function_tool
@function_tool
def get_current_time() -> str:
"""Get the current date and time."""
from datetime import datetime
return datetime.now().isoformat()
agent = Agent(
name="My agent",
instructions="You are a helpful assistant.",
model="databricks-claude-sonnet-4-5",
tools=[get_current_time],
)
LangGraph
LangChain'den @tool dekoratör kullanın:
from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent
from databricks_langchain import ChatDatabricks
@tool
def get_current_time() -> str:
"""Get the current date and time."""
from datetime import datetime
return datetime.now().isoformat()
agent = create_react_agent(
ChatDatabricks(endpoint="databricks-claude-sonnet-4-5"),
tools=[get_current_time],
)
Yerel işlev araçları, ajan süreci içinde çalıştırıldığından, databricks.yml'de kaynak ataması gerektirmez.
Adım 4. Unity AI Gateway ile Databricks Uygulamalarındaki aracılarınızdan LLM kullanımını yönetme
Aracınızın LLM çağrılarını Unity AI Gateway (Beta) aracılığıyla yönlendirerek hangi sağlayıcının yanıt verdiğine bakılmaksızın her isteğin aynı denetimler tarafından yönetilmesini sağlayın. İstek yolundaki ağ geçidiyle, aracı kodunu veya sağlayıcı kimlik bilgilerini değiştirmeden, izinleri merkezileştirebilir, uygulama başına maliyeti atayabilir, modelleri değiştirip trafiği inceleyebilir veya tekrar yürütme işlemi yapabilirsiniz.
Important
Bu özellik Beta sürümündedir. Çalışma alanı yöneticileri Bu özelliğe erişimi Önizlemeler sayfasından denetleyebilir. Bkz. Azure Databricks önizlemelerini yönetme.
Çalışma alanınızda Unity AI Gateway'i etkinleştirin. Unity AI Gateway, Beta süresince isteğe bağlıdır. Ağ geçidi uç noktalarını oluşturabilmeniz veya sorgulayabilmeniz için önce hesap yöneticisinin hesap konsolu Önizlemeler sayfasından açması gerekir. Bkz. Azure Databricks önizlemelerini yönetme.
Ajanınızı bir Unity AI Gateway uç noktasına yönlendirin. Aracı kodunda, Unity AI Gateway uç noktası adını
modelbağımsız değişkeni olarak iletin ve Azure Databricks LLM istemcisindeuse_ai_gateway=Truedeğerini ayarlayın. İstemci trafiği ağ geçidi üzerinden yönlendirir ve kimlik doğrulamasını otomatik olarak işler.OpenAI
from agents import Agent, set_default_openai_api, set_default_openai_client from databricks_openai import AsyncDatabricksOpenAI set_default_openai_client(AsyncDatabricksOpenAI(use_ai_gateway=True)) set_default_openai_api("chat_completions") agent = Agent( name="Agent", instructions="You are a helpful assistant.", model="<ai-gateway-endpoint>", )LangGraph
from databricks_langchain import ChatDatabricks llm = ChatDatabricks( model="<ai-gateway-endpoint>", use_ai_gateway=True, )Ek API’ler (OpenAI Responses API, Anthropic Messages API, Google Gemini) ve REST örnekleri için bkz. Model hizmetlerini sorgulama.
Gelişmiş yazma konuları
Akış yanıtları
Akış yanıtları
Akış, aracıların yanıtların tamamını beklemek yerine gerçek zamanlı parçalar halinde göndermesine olanak tanır. Akış uygulamak için ResponsesAgent kullanarak bir dizi delta olayını ve son olarak bir tamamlama olayını yayınlayın.
-
Delta olayları yay: Metin öbeklerini gerçek zamanlı olarak akışa almak için aynı
output_text.deltaolan birden çokitem_idolay gönderin. -
Bitti olayıyla bitir: Tam son
response.output_item.doneçıkış metnini içeren delta olaylarıyla aynıitem_idson olayı gönderin.
Her bir delta olayı, istemciye bir metin parçasını akıtır. Son tamamlanan olay, tam yanıt metnini içerir ve Databricks'e aşağıdakileri yapması için sinyal verir:
- MLflow izleme ile aracınızın çıktısını izleyin
- Unity AI Gateway çıkarım tablolarında akışlı yanıtları toplama
- AI Playground kullanıcı arabiriminde tam çıkışı gösterme
Akış hatası yayma
Azure Databricks, akış sırasında karşılaşılan hataları databricks_output.error altındaki son belirteçle iletir. Bu hatayı düzgün bir şekilde işlemek ve ortaya çıkarabilmek çağıran istemciye bağlı.
{
"delta": …,
"databricks_output": {
"trace": {...},
"error": {
"error_code": BAD_REQUEST,
"message": "TimeoutException: Tool XYZ failed to execute."
}
}
}
Özel girişler ve çıkışlar
Özel girişler ve çıkışlar
Bazı senaryolarda, client_type ve session_id gibi ilave aracı girişleri veya gelecekteki etkileşimler için sohbet geçmişine dahil edilmemesi gereken alma kaynağı bağlantıları gibi çıkışlar gerekebilir.
Bu senaryolar için MLflow ResponsesAgentcustom_inputs ve custom_outputsalanlarını yerel olarak destekler. Özel girişlere yukarıdaki çerçeve örneklerinden request.custom_inputs erişebilirsiniz.
Aracı Değerlendirme gözden geçirme uygulaması, ek giriş alanları olan aracılar için işleme izlemelerini desteklemez.
AI Playground ve inceleme uygulamasında sağlacustom_inputs
Eğer temsilciniz custom_inputs alanını kullanarak ek girişleri kabul ediyorsa, bu girişleri hem AI Playground hem de inceleme uygulamasında manuel olarak sağlayabilirsiniz.
AI Playground veya Aracı İnceleme Uygulaması'nda dişli simgesini
seçin.
özel girişlerietkinleştirin.
Aracınızın tanımlı giriş şemasıyla eşleşen bir JSON nesnesi sağlayın.
5. Adım. Aracı uygulamasını yerel olarak çalıştırma
Yerel ortamınızı ayarlayın:
uv(Python paket yöneticisi),nvm(Node sürüm yöneticisi) ve Databricks CLI'yi yükleyin:-
uvYükleme -
nvmYükleme - Node 20 LTS'yi kullanmak için aşağıdakileri çalıştırın:
nvm use 20 -
databricks CLIYükleme
-
agent-openai-agents-sdkdizinine geçin.Bağımlılıkları yüklemek, ortamınızı ayarlamak ve uygulamayı başlatmak için sağlanan hızlı başlangıç betiklerini çalıştırın.
uv run quickstart uv run start-app
Tarayıcıda yerleşik sohbet kullanıcı arabirimini açmak için adresine gidin http://localhost:8000 ve aracıyla sohbet etmeye başlayın.
Adım 6. Kimlik doğrulamasını yapılandırma
Aracınızın Azure Databricks kaynaklara erişmek için kimlik doğrulamasına ihtiyacı vardır. Databricks Apps iki kimlik doğrulama yöntemi sağlar: uygulama yetkilendirmesi (hizmet sorumlusu) ve kullanıcı yetkilendirmesi (kullanıcı adına). Çalışma alanı kullanıcı arabirimi aracılığıyla veya databricks.yml içinde Deklaratif Otomasyon Paketleri ile deklaratif olarak birini yapılandırabilirsiniz. Aracı şablonları, databricks.yml ile birlikte gönderildiğinden, şablondan başladığınızda varsayılan yol budur.
Desteklenen tüm kaynak türleri, izin değerleri ve uçtan uca databricks.yml kılavuz dahil olmak üzere tam başvuru için bkz. Yapay zeka aracıları için kimlik doğrulaması.
Uygulama yetkilendirmesi (varsayılan)
Azure Databricks, uygulamanız için otomatik olarak bir hizmet sorumlusu kullanarak uygulama yetkilendirmesi yapar. Tüm kullanıcılar aynı izinleri paylaşır.
aracının kullandığı her kaynağı resources.apps.<app>.resources altında databricks.yml içinde bildirin. Hizmet sorumlusuna bildirilen izinleri vermek için paketi dağıtın:
resources:
apps:
agent_openai_agents_sdk:
name: 'agent-openai-agents-sdk'
source_code_path: ./
config:
command: ['uv', 'run', 'start-app']
env:
- name: MLFLOW_TRACKING_URI
value: 'databricks'
- name: MLFLOW_REGISTRY_URI
value: 'databricks-uc'
- name: MLFLOW_EXPERIMENT_ID
value_from: 'experiment'
resources:
- name: 'experiment'
experiment:
experiment_id: '<experiment-id>'
permission: 'CAN_EDIT'
- name: 'llm'
serving_endpoint:
name: 'databricks-claude-sonnet-4-5'
permission: 'CAN_QUERY'
databricks bundle deploy
databricks bundle run agent_openai_agents_sdk
Kaynak türlerinin tam listesi için bkz. Uygulama yetkilendirme.
Kullanıcı yetkilendirmesi
Kullanıcı yetkilendirmesi, aracınızın her kullanıcının bireysel izinleri ile işlem yapmasını sağlar. Kullanıcı başına erişim denetimine veya denetim izlerine ihtiyacınız olduğunda bunu kullanın.
Bu kodu aracınıza ekleyin:
from agent_server.utils import get_user_workspace_client
# In your agent code (inside @invoke or @stream)
user_workspace = get_user_workspace_client()
# Access resources with the user's permissions
response = user_workspace.serving_endpoints.query(name="my-endpoint", inputs=inputs)
Important
Uygulama başlatma sırasında değil, get_user_workspace_client() veya @invoke işlevlerinizin içinde @stream başlatın. Kullanıcı kimlik bilgileri yalnızca bir isteği işlerken bulunur.
user_api_scopes'da uygulamadaki databricks.yml altına kapsamlar ekleyerek aracının kullanıcı adına hangi Azure Databricks API'lerini çağırabileceğini yapılandırın:
resources:
apps:
agent_openai_agents_sdk:
name: 'agent-openai-agents-sdk'
source_code_path: ./
user_api_scopes:
- sql
- genie
- model-serving
databricks bundle deploy
databricks bundle run agent_openai_agents_sdk
Kullanılabilir kapsamların listesi ve tam kurulum yönergeleri için bkz. Kullanıcı yetkilendirmesi.
7. Adım. Temsilciyi değerlendir
Şablon aracı değerlendirme kodunu içerir. Daha fazla bilgi için bkz. agent_server/evaluate_agent.py. Bir terminalde aşağıdakileri çalıştırarak aracınızın yanıtlarının uygunluğunu ve güvenliğini değerlendirin.
uv run agent-evaluate
8. Adım. Ajanjı Databricks Uygulamalarına dağıtın
Kimlik doğrulamasını yapılandırdıktan sonra aracınızı Azure Databricks dağıtın. Aracı şablonları, dağıtım için Databricks Varlık Paketleri'ni (DABs) kullanır.
databricks.yml Şablondaki dosya, uygulama yapılandırmasını ve kaynak izinlerini tanımlar.
Databricks CLI'nın yüklü ve yapılandırılmış olduğundan emin olun.
Note
Uygulamanızı 1. Adımda Çalışma Alanı kullanıcı arabirimi aracılığıyla oluşturduysanız, mevcut uygulamayı paketinize bağlamak için dağıtmadan önce komutunu çalıştırın databricks bundle deployment bind agent_openai_agents_sdk <app-name> --auto-approve . Aksi takdirde, databricks bundle deploy "Aynı ada sahip bir uygulama zaten var" hata verir.
Dağıtmadan önce hataları yakalamak için paket yapılandırmasını doğrulayın:
databricks bundle validatePaketi dağıtın. Bu, kodunuzu karşıya yükler ve
databricks.yml'da tanımlanan kaynakları (MLflow denemesi, servis uç noktaları vb.) yapılandırır.databricks bundle deployUygulamayı başlatın veya yeniden başlatın:
databricks bundle run agent_openai_agents_sdkNote
bundle deployyalnızca dosyaları karşıya yükler ve kaynakları yapılandırır.bundle runyeni kodla uygulamayı başlatmak veya yeniden başlatmak için gereklidir.
Gelecekteki güncellemeler için, databricks bundle deploy komutunu ve ardından databricks bundle run agent_openai_agents_sdk komutunu çalıştırarak yeniden dağıtım yapın.
Adım 9. Dağıtılan aracıyı sorgula
Aşağıdaki örnek, OAuth belirteci ile hızlı curl bir istek kullanır. Databricks Uygulamaları için kişisel erişim belirteçleri (PAT) desteklenmez.
Databricks OpenAI İstemcisi ve REST API dahil olmak üzere sorgu yöntemlerinin tam listesi için bkz. Azure Databricks'te dağıtılan aracıyı sorgulama.
Databricks CLI kullanarak bir OAuth belirteci oluşturun:
databricks auth login --host <https://host.databricks.com>
databricks auth token
Temsilciyi sorgulamak için belirteci kullanın.
curl -X POST <app-url.databricksapps.com>/responses \
-H "Authorization: Bearer <oauth token>" \
-H "Content-Type: application/json" \
-d '{ "input": [{ "role": "user", "content": "hi" }], "stream": true }'
Azure Databricks özellikleriyle uyumluluğu sağlamak için model imzalarını anlama
Azure Databricks, aracıların giriş ve çıkış şemasını tanımlamak için MLflow Model İmzalarını kullanır. AI Playground gibi ürün özellikleri, temsilcinizin desteklenen model imzalarından birine sahip olduğunu varsayar.
ResponsesAgent arabirimini kullanarak aracı yazma konusunda önerilen yaklaşımı izlerseniz, MLflow aracınız için Azure Databricks ürün özellikleriyle uyumlu bir imzayı otomatik olarak çıkaracaktır.
Limitations
- Yalnızca orta ve büyük işlem boyutları desteklenir. Bkz . Databricks uygulaması için işlem kaynaklarını yapılandırma.
- MLflow Gözden Geçirme Uygulaması Sohbeti kullanıcı arabirimi şu anda Databricks Uygulamalarına dağıtılan aracıları desteklememektedir. Mevcut izlemeleri değerlendirmek için, dağıtım yönteminden bağımsız olarak çalışan etiketleme oturumlarını kullanın. Databricks, doğrudan sohbet botu şablonuna inceleme ve geri bildirim desteği oluşturuyor.
Sonraki Adımlar
Temsilciniz geliştirme aşamasında çalıştığında, aracıyı üretime alın. Önerilen sıra için Databricks Apps aracınızı üretime alma bölümüne bakın: CI/CD, yük testi ve ardından Unity AI Gateway.