Aracı Model Hizmetleri'nden Databricks Uygulamalarına geçirme

Model Sunma uç noktasından databricks uygulamalarına mevcut bir yapay zeka aracısını geçirme.

Databricks, Model Sunma'ya göre aşağıdaki avantajları sağladığından Databricks Uygulamalarında aracı yazmanızı önerir:

• Hızlı yineleme: Saniyeler içinde aracı kodu ve dağıtım yapılandırmasını yineleyin, yerel hata ayıklama yaparak ve günlüklerde ve aracı davranışında tam şeffaflık sağlayarak.
• Git tabanlı sürüm oluşturma ve CI/CD: Git ile modüler Python aracı kodunu paketleyip sürüme alın ve Bildirim temelli Otomasyon Paketleri ile dağıtın.
• Yapay zeka kodlama yardımcısı desteği: Aracınızı yerel olarak geliştirmek ve geçirmek için yapay zeka kodlama yardımcılarını kullanın.
• Ölçeklenebilir asenkron ajanlar: Daha yüksek eşzamanlılık için Python'un yerel asenkron desenleriyle asenkron ajanlar oluşturun.
• Esnek sunucu özelleştirmesi: Herhangi bir çerçeveyi veya yığını kullanın, özel yollar ve ara yazılım ekleyin ve LLM uç noktalarına ve araçlarına kullanıcı ve aracı kimlik doğrulamasını yapılandırın.
• MLflow takip: Aracı davranışını izlemek için MLflow git tabanlı loglanmış modelleri ve gerçek zamanlı izlemeyi kullanın.
• Yerleşik sohbet kullanıcı arabirimi: Konuşma aracısı şablonları akış, kimlik doğrulaması ve kalıcı geçmişe sahip kullanıma hazır bir sohbet arabirimi içerir.

Gereksinimler

• Model Sunma uç noktası üzerinde dağıtılan mevcut bir aracı.
• Databricks CLI yüklü ve kimliği doğrulanmış. Bkz. Databricks CLI'yı yükleme veya güncelleştirme.
• Python 3.11 veya üzeri.
• uv Paket yöneticisi. Bkz uv yüklemesi.
• Çalışma alanınızda etkinleştirilmiş Databricks Uygulamaları. Bkz. Databricks Apps çalışma alanınızı ve geliştirme ortamınızı ayarlama.

Geçiş şablonunu kopyalama

Geçiş şablonu, Databricks Uygulamaları üzerinde aracı geliştirmeye ve dağıtmaya yönelik iskelenin yanı sıra yapay zeka kodlama yardımcılarına her geçiş adımını gerçekleştirmeyi öğreten aracı beceri dosyalarını sağlar.

Şablonu kopyalayıp klasöre gidin:

git clone https://github.com/databricks/app-templates.git
cd app-templates/agent-migration-from-model-serving

Şablon klasörü aşağıdakileri içerir:

• AGENTS.md: Geçiş iş akışını açıklayan yapay zeka kodlama yardımcılarına yönelik yönergeler
• skills/: Yardımcı tarafından sırayla yürütülen her geçiş adımı için beceri dosyaları
• agent_server/: @invoke() ve @stream() işleyicileri için yer tutucu kodu ile hedef Databricks Apps aracısının iskelesi
• databricks.yml: Yer tutucu kaynak bildirimleri içeren Bildirim temelli Otomasyon Paketleri yapılandırma şablonu

Yapay zeka destekli geçiş (önerilir)

Yapay zeka destekli geçiş, bu şablonu kullanmanın önerilen yoludur. Yapay zeka kodlama yardımcısı, beceri dosyalarını okur AGENTS.md ve kod ve yapılandırma değişikliklerini otomatik olarak işler.

1. Şablon klasörünü İmleç, GitHub Copilot veya Claude gibi bir yapay zeka kodlama yardımcısında açın.
2. Yardımcıdan uç nokta adınızı sağlayarak geçişi gerçekleştirmesini isteyin:

"Migrate my Model Serving endpoint `my-agent-endpoint` to a Databricks App"

1. Yardımcı bir geçiş planı oluşturur ve her adımı yürütür:

El ile geçiş

Databricks, geçişi gerçekleştirmek için yapay zeka kodlama yardımcılarının kullanılmasını önerir. Yapay zeka kodlama yardımcısı olmadan geçiş yapmak isterseniz, aşağıdaki üst düzey adımlar işlemi açıklar.

Important

Bu adımlar genel bir üst düzey bakış sağlar ve durum bilgili ajanlar, zaman uyumsuz ve eş zamanlı dengelemeler, Unity Kataloğu öğe erişimi veya karmaşık kaynak yapılandırmaları gibi tüm geçiş senaryolarını kapsamaz.

Geçişe yardımcı olması için bir yapay zeka kodlama yardımcısı kullanın veya daha ayrıntılı bilgi için şablondaki beceriyi görünmigrate-from-model-serving.

Adım 1. Aracı yapıtlarını indirme

1. Uç noktanızdan model adını ve sürümünü alın:

databricks serving-endpoints get <endpoint-name> --output json

1. Yanıtta served_entities[0].entity_name (model adı) ve entity_version bulun, ardından nesneleri indirin.

DATABRICKS_CONFIG_PROFILE=<profile> uv run --no-project \
  --with "mlflow[databricks]>=2.15.0" \
  python3 << 'EOF'
import mlflow
mlflow.set_tracking_uri("databricks")
mlflow.artifacts.download_artifacts(
    artifact_uri="models:/<model-name>/<version>",
    dst_path="./original_mlflow_model"
)
EOF

İndirilen klasör aşağıdakileri içerir:

• MLmodel — özgün aracı için kaynak bildirimleri
• code/ — aracının Python kaynak dosyaları
• artifacts/ — isteğe bağlı yapılandırma dosyaları ve istemleri
• input_example.json — test için örnek istek

Adım 2. Ajan kodunu aktarma

code/'daki tüm Python dosyalarını agent_server/'e ve artifacts/'daki herhangi bir yapıtı agent_server/artifacts/'e kopyalayın.

Dosyaları taşıdıktan sonra, yeni klasör yapısını yansıtacak şekilde göreli içeri aktarmaları ve sabit kodlanmış dosya yollarını güncelleştirin. Ardından 3. Adımda gösterilen deseni kullanmak için yeniden yazın agent_server/agent.py .

Adım 3. Aracı kodunu dönüştürme

Model Sunma'da, aracılar ResponsesAgent ile predict() ve predict_stream() yöntemlerini kullanan sınıf tabanlı bir yöntem kullanır. Databricks Uygulamalarında MLflowAgentServer, @invoke() ve @stream() ile dekore edilmiş modül düzeyi işlevler sunar.

Geçiş yaparken aşağıdaki desenlerden birini seçin:

• Async (önerilir): Birden çok isteği eşzamanlı olarak işlemek için Python async def ve await kullanır. Bir istek LLM yanıtını beklerken, sunucu diğer istekleri işler.
• Eşitleme: Model Sunma aracınızdan gelen zaman uyumlu Python desenlerini korur. En düşük geçiş için veya kodunuz yalnızca zaman uyumlu kitaplıklara bağlıysa bunu seçin.

Model Sunumu (önce)

Orijinal sınıf tabanlı ajan yapısı.

from mlflow.pyfunc import ResponsesAgent, ResponsesAgentRequest, ResponsesAgentResponse

class MyAgent(ResponsesAgent):
  def predict(self, request: ResponsesAgentRequest, params=None) -> ResponsesAgentResponse:
    # Synchronous implementation
    ...
    return ResponsesAgentResponse(output=outputs)

  def predict_stream(self, request: ResponsesAgentRequest, params=None):
    # Synchronous generator
    for chunk in ...:
      yield ResponsesAgentStreamEvent(...)

Uygulamalar — eşzamanlı olmayan (önerilen)

Temel ajan mantığı streaming() içinde bulunur. İşlev çıkışını non_streaming() toplar ve tek bir yanıt olarak döndürür.

from mlflow.genai.agent_server import invoke, stream
from mlflow.types.responses import (
  ResponsesAgentRequest,
  ResponsesAgentResponse,
  ResponsesAgentStreamEvent,
)

@invoke()
async def non_streaming(request: ResponsesAgentRequest) -> ResponsesAgentResponse:
  # Async implementation - typically calls streaming() and collects results
  outputs = [
    event.item
    async for event in streaming(request)
    if event.type == "response.output_item.done"
  ]
  return ResponsesAgentResponse(output=outputs)

@stream()
async def streaming(request: ResponsesAgentRequest) -> AsyncGenerator[ResponsesAgentStreamEvent, None]:
  # Async generator
  async for event in ...:
    yield event

Uygulamalar — eşitleme

Sınıf yöntemlerini en düşük yapısal değişikliklerle dekore edilmiş modül düzeyinde işlevlere ayıklayın.

from mlflow.genai.agent_server import invoke, stream
from mlflow.types.responses import (
  ResponsesAgentRequest,
  ResponsesAgentResponse,
  ResponsesAgentStreamEvent,
)

@invoke()
def non_streaming(request: ResponsesAgentRequest) -> ResponsesAgentResponse:
  # Same sync logic from original predict(), extracted from the class
  ...
  return ResponsesAgentResponse(output=outputs)

@stream()
def streaming(request: ResponsesAgentRequest):
  # Same sync generator from original predict_stream(), extracted from the class
  for chunk in ...:
    yield ResponsesAgentStreamEvent(...)

4. Adım. Uygulamayı ayarlama

1. Bağımlılıkları yükleyin. Bu, içindeki pyproject.toml bağımlılıkları çözer ve yeniden üretilebilir yüklemeler için bunları sabitleyen dosyayı oluşturur uv.lock :

   uv sync
   

2. Kimlik doğrulamayı yapılandırmak, MLflow deneyini oluşturmak ve .env dosyasını oluşturmak için hızlı başlangıç betiğini çalıştırın:

   uv run quickstart
   

Databricks Apps'in dağıttığınızda aynı sabitlenmiş bağımlılıkları yüklemesi için oluşturulan uv.lock dosyayı işleyin.

5. Adım. Yerel olarak test et

Uygulama sunucusunu başlatın ve dağıtmadan önce aracının doğru yanıt verdiğini doğrulayın.

Curl kullanarak özgün input_example.json testinizi yapın, ardından aracı beklendiği gibi yanıt verdikten sonra dağıtın.

6. Adım. Kaynakları yapılandırma

Model Sunma aracıları bir MLmodel dosyadaki kaynakları bildirir. Databricks Apps aracıları Bildirim temelli Otomasyon Paketlerini kullanarak yapılandırma dosyasındaki databricks.yml kaynakları bildirir.

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

Kaynak bildirimlerinizi eşdeğer Bildirim temelli Otomasyon Paketleri biçimiyle eşleyin:

MLmodel kaynak türü	databricks.yml Eşdeğer	İzin
serving_endpoint	serving_endpoint	CAN_QUERY
lakebase	database	CAN_CONNECT_AND_CREATE
vector_search_index	uc_securable (güvenli_tip: TABLE)	SELECT
function	uc_securable (güvenli_tip: FUNCTION)	EXECUTE
table	uc_securable (güvenli_tip: TABLE)	SELECT veya MODIFY
uc_connection	uc_securable (güvenli_tip: CONNECTION)	USE_CONNECTION
sql_warehouse	sql_warehouse	CAN_USE
genie_space	genie_space	CAN_RUN

7. Adım. Bildirim temelli Otomasyon Paketlerini kullanarak aracıyı dağıtma

Bildirim temelli Otomasyon Paketlerini kullanarak aracınızı Databricks Uygulamalarına dağıtın.

Dağıtmadan önce klasör yapınızın aşağıdaki gibi göründüğünü doğrulayın:

<working-directory>/
├── original_mlflow_model/    # Downloaded artifacts from Model Serving
│   ├── MLmodel
│   ├── code/
│   │   └── agent.py
│   ├── input_example.json
│   └── requirements.txt
│
└── <app-name>/               # New Databricks App (ready to deploy)
    ├── agent_server/
    │   ├── agent.py          # Migrated agent code
    │   └── ...
    ├── app.yaml
    ├── databricks.yml        # Bundle config with resources
    ├── pyproject.toml        # Python dependencies (uv)
    ├── uv.lock               # Pinned dependencies for reproducible installs
    └── ...

Note

Azure Databricks, daha hızlı yüklemeler ve yeniden üretilebilir derlemeler sağlayan Python bağımlılık yönetimi için uv (pyproject.toml + uv.lock) önerir. Uygulamanız bir pyproject.toml ve uv.lock içerip requirements.txt içermediğinde, Databricks Apps bağımlılıkları yüklemek için uv kullanır. requirements.txt desteklenmeye devam eder: varsa, her zaman öncelik kazanır ve Databricks Apps bunun yerine kullanır pip . Bkz. Databricks Uygulamaları için en iyi yöntemler ve ile uvPython bağımlılıkları tanımlama.

1. Paket yapılandırmasını doğrulayın:

   databricks bundle validate
   

2. Paketi çalışma alanınıza dağıtın (bundle deploy dosyaları karşıya yükler ancak uygulamayı başlatmaz):

   databricks bundle deploy
   

3. Uygulamayı başlatın:

   databricks bundle run <app-resource-name>
   

Ek kaynaklar

Ajanınızı geçirdikten sonra bkz:

• Bir yapay zeka aracısı yazma ve Databricks Uygulamalarında dağıtma
• Özel kod aracısının hatalarını ayıklama
• Yapay zeka aracıları için kimlik doğrulaması
• Yapay zeka kodlama yardımcıları için ajan becerileri
• Databricks Uygulamaları için ağı yapılandırma