Özel Web API vektörleştiricisi

Not

Azure Yapay Zeka Arama Azure portalı, REST API'leri ve Azure SDK’ları aracılığıyla kullanılabilir. Ayrıca kuruluş içeriğini Microsoft Foundry portalındaki aracılar için yeniden kullanılabilir, izin kullanan bilgi bankalarına dönüştüren yönetilen bilgi katmanı Foundry IQ'yu temel alır.

Özel Web API vektörleştiricisi, arama sorgularını, sorgu zamanında eklemeler oluşturan bir web API uç noktasını çağıracak şekilde yapılandırmanıza olanak tanır. Uç nokta için gerekli JSON yük yapısı bu makalenin devamında açıklanmıştır. Verileriniz, modelinizin dağıtıldığı bölge işlenir.

Vektörleştiriciler sorgu zamanında kullanılasa da, bunları dizin tanımlarında belirtir ve vektör alanlarında bir vektör profili aracılığıyla başvurursunuz. Daha fazla bilgi için bkz. Arama dizininde vektörleştirici yapılandırma.

Özel web API vektörleştiricisi REST API'de çağrılır WebApiVectorizer . Indexes - Create (REST API) veya özelliği sağlayan bir Azure SDK paketinin en son kararlı sürümünü kullanın.

Vektörleştirici parametreleri

Parametreler büyük/küçük harfe duyarlıdır.

Parametre adı	Açıklama
`uri`	JSON yükünün gönderildiği Web API'sinin URI'sini. Yalnızca https URI düzenine izin verilir. GET ile dizini aldığınızda, hizmet işlev anahtarlarının `?code=` açığa çıkmasını önlemek için olarak sorgu parametresi değerini `?code=<redacted>` döndürür. Depolanan URI'yi değiştirmeden vektörleştiriciyi güncellemek için `uri` değerini `<unchanged>` olarak ayarlayın.
`httpMethod`	Yükü göndermek için kullanılan yöntem. İzin verilen yöntemler `PUT` veya `POST`.
`httpHeaders`	Anahtarların üst bilgi adları olduğu ve değerlerin web API'nize gönderildiği anahtar-değer çiftleri koleksiyonu. Aşağıdaki üst bilgiler yasaktır: , , , , , `Accept`, `Accept-Charset`, `Accept-Encoding`, `Content-LengthContent-Type`ve `Cookie`. `HostTEUpgradeVia` GET, her üst bilgi değeri `<redacted>` için sentinel değerini döndürür. Güncelleştirme gereksinimleri için bkz . GET sonrasında üst bilgi değerlerini güncelleştirme.
`authResourceId`	(İsteğe bağlı) Ayarlanırsa, bu vektörleştiricinin kodu barındıran işleve veya uygulamaya bağlantı için yönetilen kimlik kullandığını gösteren bir dize. Bu özellik şu biçimlerden birinde Microsoft Entra ID bir uygulama (istemci) kimliği veya uygulama kaydı alır: `api://<appId>`, `<appId>/.default`, `api://<appId>/.default`. Bu değer, sorgu işlem hattı tarafından alınan ve işleve veya uygulamaya özel web API isteğiyle gönderilen kimlik doğrulama belirtecinin kapsamını kapsar. Bu özelliği ayarlamak için, arama hizmetinizin yönetilen kimlik için ayarlandığı ve Azure işlev uygulamanızın Microsoft Entra oturum açma için ayarlandığı gerekir.
`authIdentity`	(İsteğe bağlı) Kullanıcı tarafından yönetilen kimlik, kod barındıran işlev veya uygulamaya bağlanmak için arama hizmeti tarafından kullanılır. Sistem tarafından yönetilen veya kullanıcı tarafından yönetilen bir kimlik kullanabilirsiniz. Sistem tarafından yönetilen bir kimlik kullanmak istiyorsanız, `authIdentity` boş bırakılmalıdır.
`timeout`	(İsteğe bağlı) API çağrısı yapan HTTP istemcisinin zaman aşımı. XSD `dayTimeDuration` değeri ( ISO 8601 süre değerinin kısıtlanmış bir alt kümesi) olarak biçimlendirilmelidir. Örneğin, `PT60S` 60 saniye anlamına gelir. Ayarlanmadıysa, varsayılan değer 30 saniyedir. Zaman aşımı 1 ile 230 saniye arasında olabilir.

Desteklenen vektör sorgu türleri

Özel Web API vektörleştiricisi , textve imageUrl vektör sorgularını desteklerimageBinary.

Örnek tanım

"vectorizers": [
    {
        "name": "my-custom-web-api-vectorizer",
        "kind": "customWebApi",
        "customWebApiParameters": {
            "uri": "https://contoso.embeddings.com",
            "httpMethod": "POST",
            "httpHeaders": {
                "api-key": "<your-header-value>"
            },
            "timeout": "PT60S",
            "authResourceId": null,
            "authIdentity": null
        }
    }
]

GET sonrasında üst bilgi değerlerini güncelleştirme

Bir dizin tanımı aldığınızda, hizmet Özel Web API vektörleştiricisindeki her <redacted> değer için sentinel httpHeaders değerini döndürür. Örneğin:

{
    "name": "my-custom-web-api-vectorizer",
    "kind": "customWebApi",
    "customWebApiParameters": {
        "uri": "https://contoso.embeddings.com",
        "httpMethod": "POST",
        "httpHeaders": {
            "api-key": "<redacted>"
        },
        "timeout": "PT60S",
        "authResourceId": null,
        "authIdentity": null
    }
}

Depolanan api-key değeri yeniden kullanmak için, aynı mevcut vektörleştiriciyi aynı name ve kindile güncelleştirin, değişmeden bırakın uri ve eşleşen üst bilgi adı için sentinel'i yeniden gönderin:

{
    "name": "my-custom-web-api-vectorizer",
    "kind": "customWebApi",
    "customWebApiParameters": {
        "uri": "https://contoso.embeddings.com",
        "httpMethod": "POST",
        "httpHeaders": {
            "api-key": "<redacted>"
        },
        "timeout": "PT60S",
        "authResourceId": null,
        "authIdentity": null
    }
}

Değişmemiş uribir ile, korunan üst bilgi değerlerini diğer mevcut üst bilgiler için gerçek değiştirme değerleriyle karıştırabilirsiniz <redacted> . Sentinel yalnızca aynı vektörleştiricide aynı ada sahip mevcut bir üst bilgi için geçerli olduğundan eklenen veya yeniden adlandırılan her üst bilgi için gerçek bir değer sağlayın.

değerini değiştirirseniz uri, aynı güncelleştirmedeki her httpHeaders giriş için gerçek değerler sağlayın. Hizmet farklı bir uriiçin depolanan değerleri yeniden kullanmaz:

{
    "name": "my-custom-web-api-vectorizer",
    "kind": "customWebApi",
    "customWebApiParameters": {
        "uri": "https://new.contoso.embeddings.com",
        "httpMethod": "POST",
        "httpHeaders": {
            "api-key": "<new-header-value>"
        },
        "timeout": "PT60S",
        "authResourceId": null,
        "authIdentity": null
    }
}

Kimlik bilgileri kullanılamıyorsa ve öğesini değiştirmeniz urigerekiyorsa, bunları dış uç noktada döndürün veya yeniden üretin. Ardından yeni uri ve üst bilgi değerlerini birlikte gönderin.

Değer <redacted> , kimlik bilgisi değil hizmet sentinel değeridir. Vektörleştirici oluşturamaz veya başka bir vektörleştirici için depolanan üst bilgi değerini alamaz veya yeniden kullanamaz.

JSON yük yapısı

Özel Web API vektörleştiricisi ile kullanılan bir uç nokta için gerekli JSON yük yapısı, Özel Web API'sinin becerisi tarafından kullanılan yapıyla aynıdır. Daha fazla bilgi için beceri belgelerine bakın.

Özel Web API vektörleştiricisi için bir web API'si uç noktası uygularken aşağıdaki noktaları göz önünde bulundurun:

Vektörleştirici, uç noktaya istekte bulunurken dizide bir kerede values yalnızca bir kayıt gönderir.
Vektörleştirici, istek yükündeki JSON nesnesindeki belirli bir anahtarda data vektörleştirilecek verileri geçirir. Bu anahtar text, istenen vektör sorgusu türüne bağlı olarak , imageUrlveya imageBinaryşeklindedir.
Vektörleştirici, sonuçta elde edilen ekleme işleminin vector yanıt yükündeki JSON nesnesindeki data anahtarın altında olmasını bekler.
Vektörleştirici, uç nokta tarafından döndürülen hata veya uyarıları göz ardı eder. Bu hatalar ve uyarılar sorgu zamanı hata ayıklaması için kullanılamaz.

Bir imageBinary vektör sorgusu istendiyse uç noktaya gönderilen istek yükü aşağıdaki gibidir:

{
    "values": [
        {
            "recordId": "0",
            "data":
            {
                "imageBinary": {
                    "data": "<base 64 encoded image binary data>"
                }
            }
        }
    ]
}

Ayrıca bkz.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-08-13