Özel kod aracısının hatalarını ayıklama

Bu sayfa, Azure Databricks üzerinde dağıtılan özel kod aracılarında karşılaşılan yaygın sorunlarda nasıl hata ayıklanacağını ele alır.

Şuraya gidin:

• En iyi uygulamalar
• Yerel geliştirme
• Yapılandırma sorunları
• Dağıtım sorunları
• Çalışma zamanı hataları
• Kimlik doğrulama hataları
• Bellek ve depolama

Bu sayfadaki hata ayıklama bölümlerinin çoğu Databricks Uygulamalarına dağıtılan aracılar için geçerlidir. Ancak, sekme seçicilerini kullanarak Model Sunma 'da (eski) dağıtılan aracıların hata ayıklama bilgilerini de bulabilirsiniz.

En iyi yöntemleri kullanarak aracı oluşturma

Aracı oluştururken aşağıdaki en iyi yöntemleri kullanın:

• MLflow izlemeyi etkinleştirme: Yapay zeka aracısı yazma ve databricks uygulamalarına dağıtma konusunda en iyi yöntemleri izleyin. Aracılarınızın hata ayıklamasını kolaylaştırmak için MLflow izleme otomatik kaydetmeyi etkinleştirin.
• Belge araçlarını açıkça tanımlayın: Araç ve parametre açıklamalarını net bir şekilde belirtmek, ajanınızın araçlarınızı anlamasını ve bunları uygun şekilde kullanmasını sağlar. Bkz Açık belgelerle araç çağırmayı iyileştirin.
• LLM çağrılarına zaman aşımları ve belirteç sınırları ekleme: Uzun süre çalışan adımlardan kaynaklanan gecikmeleri önlemek için kodunuzdaki LLM çağrılarına zaman aşımları ve belirteç sınırları ekleyin.
  • Aracınız Bir Azure Databricks LLM sunum uç noktasını sorgulamak için OpenAI istemcisini kullanıyorsa, hizmet veren uç nokta çağrılarında gerektiğinde özel zaman aşımları ayarlayın.
• Dağıtımdan önce yapılandırmayı doğrulama: YAML yapılandırma sorunlarını erken yakalamak için dağıtmadan önce çalıştırın databricks bundle validate . Bu, eşleşmeyen kaynak başvurularını, geçersiz izinleri ve söz dizimi hatalarını tanımlamaya yardımcı olur.
• Önce yerel olarak test edin: Dağıtmadan önce sorunları yakalamak için yerel geliştirmeyi kullanın. Aracı sunucunuzu yerel olarak başlatın, örnek isteklerle test edin ve Databricks Uygulamalarına dağıtmadan önce MLflow izlemelerinin doğru göründüğünü doğrulayın.

Yerel geliştirme sorunlarının hatalarını ayıklama

Dağıtımdan önce sorunları belirlemek için aracınızı yerel olarak test edin.

Aracınızı yerel olarak çalıştırmadan önce ortamınızın doğru yapılandırıldığını doğrulayın:

1. Databricks CLI sürümünü denetleyin: 0.283.0 veya sonraki bir sürüme sahip olduğunuzu doğrulamak için komutunu çalıştırın databricks -v .

2. CLI profillerini doğrulama: Yapılandırılan kimlik doğrulama profillerini görmek için komutunu çalıştırın databricks auth profiles .

3. Ortam yapılandırmasını doğrulama: Dosyanızın, cli profilinizi .env dahil etmek için biçimini MLFLOW_TRACKING_URI kullanması gereken gerekli değişkenleri( özellikledatabricks://PROFILE_NAME) içerdiğini denetleyin.

Yaygın yerel geliştirme hataları

Ajanı yerel olarak test edin

Dağıtımdan önce aracınızı test etmek için:

1. Aracı sunucusunu yerel olarak başlatın:

   uv run start-app
   

2. Başka bir terminalde bir test isteği gönderin:

   curl -X POST http://localhost:8000/invocations \
     -H "Content-Type: application/json" \
     -d '{"input": [{"role": "user", "content": "hello"}]}'
   

3. Aracınızın izlemeleri doğru şekilde günlüğe kaydetmesini doğrulamak için Azure Databricks kullanıcı arabiriminde MLflow izlemelerini görüntüleyin.

Hata ayıklama yapılandırma sorunları

ve databricks.yml içindeki app.yaml yapılandırma hataları, yaygın dağıtım hatalarının kaynaklarıdır.

Bildirim temelli Otomasyon Paketleri yapılandırmasını doğrulama

Uygulamayı dağıtmadan önce Bildirim temelli Otomasyon Paketleri yapılandırmasını doğrulayın:

databricks bundle validate

Bu komut yapılandırmanızı denetler:

• YAML sözdizimi hataları
• Eksik gerekli alanlar
• Geçersiz kaynak başvuruları
• İzin yapılandırma sorunları

Yaygın yapılandırma uyuşmazlıkları

Dağıtım sorunlarını ayıklama

Uygulamalara dağıtılan aracılar

# Get existing app configuration
databricks apps get <app-name> --output json

# Sync the configuration to your databricks.yml, then bind
databricks bundle deployment bind <bundle-name> <app-name> --auto-approve

# Deploy
databricks bundle deploy
databricks bundle run <bundle-name>

databricks apps delete <app-name>
databricks bundle deploy
databricks bundle run <bundle-name>

databricks bundle deploy && databricks bundle run <bundle-name>

databricks apps get <app-name>

databricks apps logs <app-name> --follow

Model Servis Agent'leri (Eski)

Eğer aracınızı agents.deploy() kullanarak Model Sunma uç noktasına dağıttıysanız, dağıtıma özgü sorunlar için Model Sunma Hata Ayıklama kılavuzunu gözden geçirin.

Yavaş veya başarısız istekler gibi çalışma zamanı sorunlarını ayıklamak için bkz. Çalışma zamanı hatalarını ayıklama.

Çalışma zamanı hatalarını ayıklama

Uygulamalara dağıtılan aracılar

Dağıtılan aracınızla ilgili sorunları belirlemek için uygulama günlüklerini ve istek testini kullanın.

Uygulama günlüklerini analiz etme

Dağıtılan uygulamanızdan gerçek zamanlı günlükleri görüntüleyin:

databricks apps logs <app-name> --follow

Şunu arayın:

• Kod hatalarını gösteren yığın izlemeleri
• Kaynaklar için izin reddedildi iletileri
• Dış hizmetlere bağlantı hataları
• Zaman aşımı iletileri

Yaygın çalışma zamanı hataları

Model Servis Agent'leri (Eski)

Model Sunma uç noktalarına dağıtılan aracılarla ilgili sorunları belirlemek için çıkarım tablolarını ve MLflow izlemelerini kullanın.

Sorunlu istekleri tanımlama

Ajanınızı oluştururken MLflow iz otomatik kaydetmeyi etkinleştirdiyseniz, izler çıkarım tablolarına otomatik olarak kaydedilir. Yavaş veya başarısız olan aracı bileşenlerini tanımlamak için bu izlemeleri kullanın.

1. Çalışma alanınızda , Sunum sekmesine gidin ve dağıtım adınızı seçin.
2. Çıkarım tabloları bölümünde çıkarım tablosunun tam adını bulun. Örneğin, my-catalog.my-schema.my-table.
3. Databricks not defterinde aşağıdakileri çalıştırın:

   %sql
   SELECT * FROM my-catalog.my-schema.my-table
   

4. Ayrıntılı izleme bilgileri için Yanıt sütununu inceleyin.
5. Sonuçları daraltmak için request_time, databricks_request_id veya status_code üzerinde filtreleyin.

   %sql
   SELECT * FROM my-catalog.my-schema.my-table
   WHERE status_code != 200
   

Kök neden sorunlarını analiz etme

Başarısız veya yavaş istekleri belirledikten sonra, başarısız giriş isteğine karşı aracınızı çağırmak için mlflow.models.validate_serving_input API'sini kullanın. Elde edilen iz sonucunu görüntüleyin ve başarısız yanıt üzerinde kök neden analizi gerçekleştirin.

Daha hızlı bir geliştirme döngüsü için aracı kodunuzu doğrudan güncelleştirin ve aracınızı başarısız giriş örneğine karşı çağırarak yineleyin.

Kimlik doğrulama hatalarını ayıklama

Uygulamalara dağıtılan aracılar

databricks auth token

TOKEN=$(databricks auth token | jq -r '.access_token')
curl -X POST <app-url>/invocations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": [{"role": "user", "content": "hello"}]}'

resources:
  apps:
    my_agent:
      name: 'agent-my-app'
      resources:
        - name: 'my_genie_space'
          genie_space:
            space_id: '01234567890abcdef01234567890abcd'
            permission: 'CAN_RUN'
        - name: 'my_vector_index'
          uc_securable:
            securable_full_name: 'catalog.schema.index_name'
            securable_type: 'TABLE'
            permission: 'SELECT'

# Get your agent app's service principal
AGENT_SP=$(databricks apps get <agent-app-name> --output json | jq -r '.service_principal_name')

# Grant permission on the MCP server app
databricks apps update-permissions <mcp-server-app-name> \
  --json "{\"access_control_list\": [{\"service_principal_name\": \"$AGENT_SP\", \"permission_level\": \"CAN_USE\"}]}"

Model Servis Agent'leri (Eski)

Dağıtılan aracınız AI Search dizinleri veya LLM uç noktaları gibi kaynaklara erişirken kimlik doğrulama hatalarıyla karşılaşıyorsa, kimlik doğrulamasının otomatik olarak aktarılabilmesi için gerekli kaynaklarla ilişkilendirildiğini doğrulayın. Bkz. Otomatik kimlik doğrulaması geçişi.

Günlüğe kaydedilen kaynakları incelemek için not defterinde aşağıdakileri çalıştırın:

%pip install -U mlflow[databricks]==2.20.2
%restart_python

import mlflow
mlflow.set_registry_uri("databricks-uc")

# Replace with the model name and version of your deployed agent
agent_registered_model_name = ...
agent_model_version = ...

model_uri = f"models:/{agent_registered_model_name}/{agent_model_version}"
agent_info = mlflow.models.Model.load(model_uri)
print(f"Resources logged for agent model {model_uri}:", agent_info.resources)

Eksik veya yanlış kaynakları yeniden eklemek için aracı sisteme kaydedin ve yeniden dağıtın.

Kaynaklar için el ile kimlik doğrulaması kullanıyorsanız ortam değişkenlerinin doğru ayarlandığını doğrulayın. El ile yapılan ayarlar tüm otomatik kimlik doğrulama yapılandırmalarını geçersiz kılar. Bkz. El ile kimlik doğrulaması.

Bellek ve depolama sorunlarının hatalarını ayıklama

Bellek depolaması için Lakebase kullanan aracılar için aşağıdaki sorunlar yaygındır:

Örnek Lakebase kaynak yapılandırması:

resources:
  apps:
    my_agent:
      resources:
        - name: 'memory_database'
          database:
            instance_name: '<lakebase-instance-name>'
            database_name: 'postgres'
            permission: 'CAN_CONNECT_AND_CREATE'

Bir aracıyı bellekle dağıtmadan önce tabloları yerel olarak başlatın:

import asyncio
from databricks_langchain import AsyncDatabricksStore

async def setup_memory():
    async with AsyncDatabricksStore(
        instance_name='your-lakebase-instance',
        embedding_endpoint='databricks-gte-large-en',
        embedding_dims=1024,
    ) as store:
        await store.setup()

asyncio.run(setup_memory())