Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
Uwaga / Notatka
Foundry IQ (Wyszukiwanie AI platformy Azure) udostępnia bezpośrednie interfejsy API indeksowania i zapytań, a także interfejsy API wyższego poziomu dla źródeł wiedzy i baz wiedzy do zarządzanego pobierania. Użyj portalu Azure, interfejsów API REST lub Azure SDKs, aby skonfigurować te możliwości lub połączyć agentów z bazami wiedzy w portalu Microsoft Foundry.
W Foundry IQ (Wyszukiwanie AI platformy Azure) wektoryzator konwertuje tekst lub obrazy na wektory podczas wykonywania zapytania, umożliwiając przesyłanie zapytań w postaci zwykłego tekstu względem pól wektorów bez konieczności samodzielnego obliczania osadzeń.
Wektoryzator jest definiowany w indeksie wyszukiwania i przypisywany do pól wektorów za pośrednictwem profilu wektorowego. W czasie wykonywania zapytania wektoryzator wywołuje model osadzania w celu wygenerowania wektora na podstawie danych wejściowych zapytania. Aby uzyskać więcej informacji, zobacz Używanie zintegrowanej wektoryzacji w zapytaniach.
Aby dodać wektoryzator do indeksu, użyj kreatora importu lub projektanta indeksów w witrynie Azure Portal, indeksów — tworzenie lub aktualizowanie (interfejs API REST) lub pakiet zestawu Azure SDK. W tym artykule użyto architektury REST na potrzeby ilustracji.
Wskazówka
Wektoryzator obsługuje wektoryzację w czasie zapytania. Aby również wektoryzować zawartość podczas indeksowania, skonfiguruj indeksator i zestaw umiejętności z umiejętnością osadzania. Aby uzyskać więcej informacji, zobacz Używanie zintegrowanej wektoryzacji podczas indeksowania.
Wymagania wstępne
Indeks z polami wektorów z możliwością wyszukiwania w usłudze IQ usługi Foundry.
(Opcjonalnie) Rejestrowanie diagnostyczne włączone w usłudze IQ usługi Foundry w celu potwierdzenia wykonania zapytania wektorowego.
Obsługiwana implementacja modelu osadzania dla wektoryzatora.
Uprawnienia do aktualizowania i wykonywania zapytań względem indeksu. W tym artykule użyto zalecanego uwierzytelniania bez klucza. Przypisz role Współautor usługi wyszukiwania i Czytelnik danych indeksu wyszukiwania do konta użytkownika, zaloguj się do platformy Azure i uzyskaj token dostępu. Jeśli zamiast tego używasz kluczy interfejsu API , pobierz klucz administratora dla operacji aktualizacji i klucz zapytania dla operacji wyszukiwania.
Uprawnienia do korzystania z modelu osadzania. Na przykład w przypadku usługi Azure OpenAI obiekt wywołujący musi mieć uprawnienia Użytkownika OpenAI usług Cognitive Services. Możesz także użyć klucza API.
Visual Studio Code z rozszerzeniem klienta REST. Utwórz plik
.restlub.http, aby wysłać każde żądanie REST w tym artykule bezpośrednio z edytora.
Obsługiwane modele osadzania
Foundry IQ oferuje kilka typów wektoryzatorów, z których każdy jest powiązany z odpowiednią umiejętnością. Umiejętność generuje osadzanie podczas indeksowania, podczas gdy wektoryzator generuje osadzanie w czasie zapytania. Należy użyć tego samego modelu osadzania dla obu, więc wybierz parę wektoryzator-umiejętność, która wskazuje na to samo wdrożenie modelu.
Zmiana wektoryzatora nie powoduje ponownego wygenerowania indeksowanych wektorów dokumentów. Aby zastąpić model używany przez istniejący indeks, zobacz Migrowanie modeli osadzania.
W poniższej tabeli wymieniono wektoryzatory i obsługiwane modele oraz skojarzone z nimi umiejętności.
| Wektoryzator | Obsługiwane modele | Skojarzona umiejętność |
|---|---|---|
| Azure OpenAI | text-embedding-ada-002 osadzanie tekstu —3 — duże osadzanie-tekstu-3-mniejsze |
Azure OpenAI Embedding |
| katalog modeli Microsoft Foundry (wersja zapoznawcza) | Cohere-embed-v3-angielski Cohere-embed-v3-wielojęzyczny Cohere-embed-v4 1 |
AML |
| Azure Vision (wersja zapoznawcza) | Osadzanie wielomodalne interfejsu API 4.0 | Wielomodalne osadzanie Azure Vision (wersja zapoznawcza) |
| Niestandardowy internetowy interfejs API | Dowolny model osadzania (hostowany zewnętrznie) | Niestandardowy interfejs API sieci Web |
1 Można określić embed-v-4-0 tylko programowo za pomocą umiejętności AML lub Microsoft Foundry model catalog vectorizer, a nie za pośrednictwem portalu Azure. Można jednak użyć portalu do późniejszego zarządzania zestawem umiejętności lub wektoryzatorem.
Uwaga / Notatka
Wektoryzatory są ogólnie dostępne, o ile używasz ogólnie dostępnej pary umiejętność–wektoryzator. Aby uzyskać najnowsze informacje o dostępności, zobacz dokumentację dla każdego wektoryzatora i umiejętności w poprzedniej tabeli.
Zdefiniuj wektoryzator przy użyciu kreatora
Kreator importu danych w witrynie Azure Portal może odczytywać pliki z usługi Azure Blob Storage, tworzyć indeks z polami fragmentowanymi i wektoryzowanymi oraz dodawać wektoryzator. Zgodnie z projektem wektoryzator generowany przez kreatora jest ustawiony na ten sam model osadzania używany do indeksowania zawartości obiektu blob.
Aby utworzyć przykładowy indeks za pomocą wektoryzatora przy użyciu kreatora:
Przekaż pliki do kontenera w Azure Storage. Użyliśmy małych plików tekstowych z e-booka NASA Earth at Night, aby przetestować te instrukcje w bezpłatnej usłudze Foundry IQ.
Uruchom kreatora importowania danych. Wybierz kontener blob dla źródła danych.
Wybierz rodzaj wektoryzatora i, jeśli ma to zastosowanie, wdrożenie modelu. W tym przykładzie użyto usługi Azure OpenAI i wdrożenia modelu text-embedding-ada-002.
Po zakończeniu działania kreatora i zakończeniu przetwarzania indeksatora należy mieć indeks z polem wektora z możliwością wyszukiwania. Definicja JSON pola wygląda następująco:
{ "name": "text_vector", "type": "Collection(Edm.Single)", "searchable": true, "filterable": false, "retrievable": true, "stored": true, "sortable": false, "facetable": false, "key": false, "dimensions": 1536, "vectorSearchProfile": "vector-nasa-ebook-text-profile", "synonymMaps": [] }Należy również mieć profil wektorowy, algorytm wyszukiwania wektorów i wektoryzator. Ich definicje JSON wyglądają następująco:
"algorithms": [ { "name": "vector-nasa-ebook-text-algorithm", "kind": "hnsw", "hnswParameters": { "metric": "cosine", "m": 4, "efConstruction": 400, "efSearch": 500 } } ], "profiles": [ { "name": "vector-nasa-ebook-text-profile", "algorithm": "vector-nasa-ebook-text-algorithm", "vectorizer": "vector-nasa-ebook-text-vectorizer" } ], "vectorizers": [ { "name": "vector-nasa-ebook-text-vectorizer", "kind": "azureOpenAI", "azureOpenAIParameters": { "resourceUri": "https://my-azure-openai-resource.openai.azure.com", "deploymentId": "text-embedding-ada-002", "modelName": "text-embedding-ada-002", }, } ]
Programowe definiowanie wektoryzatora
Jeśli kreator portalu nie został użyty lub chcesz dodać wektoryzator do istniejącego indeksu, możesz programowo zdefiniować wektoryzator i profil wektorowy. Profil wektorowy łączy wektoryzatora z co najmniej jednym polem wektora i określa algorytm wyszukiwania wektorów używany do struktur nawigacji.
Aby zdefiniować wektoryzator i profil wektora w istniejącym indeksie:
Pobierz definicję indeksu przy użyciu Indexes - Get (REST API). Zastąp nazwę usługi, nazwę indeksu i token dostępu własnymi wartościami.
### Get index definition GET https://my-search-service.search.windows.net/indexes/my-index?api-version=2026-10-01 HTTP/1.1 Authorization: Bearer <your-access-token> // For API keys, replace this line with api-key: <your-admin-api-key>Warning
Pobrany wektoryzator niestandardowego internetowego interfejsu API zawiera
<redacted>dla każdej wartościhttpHeaders. Jeśli aktualizujesz ten sam wektoryzator bez zmiany wartościname,kindluburi, możesz ponownie przesłać<redacted>w celu dopasowania do istniejących nazw nagłówków. Jeśli zmienisz wartośćuri, prześlij rzeczywiste wartości dla każdegohttpHeaderswpisu. Aby uzyskać informacje o innych regułach aktualizacji, zobacz Custom Web API vectorizer (Niestandardowy wektorizer interfejsu API sieci Web).Użyj indeksów — utwórz lub zaktualizuj (interfejs API REST), aby zaktualizować definicję indeksu. Wklej pełną definicję indeksu w treści żądania.
### Update index definition PUT https://my-search-service.search.windows.net/indexes/my-index?api-version=2026-10-01 HTTP/1.1 Content-Type: application/json Authorization: Bearer <your-access-token> // For API keys, replace this line with api-key: <your-admin-api-key> // Paste your index definition hereDodaj sekcję
vectorizersdovectorSearchobiektu. Ta sekcja określa informacje o połączeniu z wdrożonym modelem osadzania. Poniższy przykład obejmuje porównanie zarówno interfejsu Azure OpenAI, jak i niestandardowego internetowego interfejsu API."vectorSearch": { "vectorizers": [ { "name": "my_azure_open_ai_vectorizer", "kind": "azureOpenAI", "azureOpenAIParameters": { "resourceUri": "https://url.openai.azure.com", "deploymentId": "text-embedding-ada-002", "modelName": "text-embedding-ada-002", "apiKey": "<your-azure-openai-api-key>" } }, { "name": "my_custom_vectorizer", "kind": "customWebApi", "customWebApiParameters": { "uri": "https://contoso.embeddings.com", "httpMethod": "POST", "authResourceId": null, "authIdentity": null } } ] }Dodaj sekcję
algorithmsdovectorSearch. W tej sekcji zdefiniowano algorytm wyszukiwania wektorowego używany do tworzenia struktur nawigacji."algorithms": [ { "name": "my_hnsw_algorithm", "kind": "hnsw", "hnswParameters": { "m": 4, "efConstruction": 400, "efSearch": 500, "metric": "cosine" } } ]Dodaj sekcję
profilesdovectorSearch. W tej sekcji odwołuje się do wektoryzatora i algorytmu wyszukiwania wektorowego zdefiniowanego w poprzednich krokach."profiles": [ { "name": "my_vector_profile", "algorithm": "my_hnsw_algorithm", "vectorizer": "my_azure_open_ai_vectorizer" } ]W tablicy
fields, przypisz profil wektora do jednego lub więcej pól wektora, określając właściwośćvectorSearchProfile."fields": [ ... // Trimmed for brevity { "name": "vector", "type": "Collection(Edm.Single)", "dimensions": 1536, "vectorSearchProfile": "my_vector_profile", "searchable": true, "retrievable": true }, { "name": "my_second_vector", "type": "Collection(Edm.Single)", "dimensions": 1536, "vectorSearchProfile": "my_vector_profile", "searchable": true, "retrievable": true } ]Wyślij żądanie PUT, aby zaktualizować definicję indeksu. Jeśli żądanie zakończy się pomyślnie, otrzymasz odpowiedź
204 No Content.Aby zweryfikować wektoryzator i profil wektora, uruchom ponownie żądanie GET w pierwszym kroku. Potwierdź, że:
Tablica
vectorSearch.vectorizerszawiera definicję wektoryzatora z poprawnymikindparametrami i parametrami połączenia.Tablica
vectorSearch.profileszawiera profil, który według nazwy odwołuje się do wektoryzatora.Tablica
vectorSearch.algorithmszawiera algorytm wyszukiwania wektorowego, do których odwołuje się Twój profil.Właściwość
vectorSearchProfilew tablicyfieldsdla pól wektorów jest zgodna z nazwą profilu.
Testowanie wektoryzatora
Aby potwierdzić działanie wektoryzatora, wyślij zapytanie wektorowe , które przekazuje ciąg tekstowy zamiast wektora. Poniższy przykład dotyczy przykładowego indeksu z sekcji Definiowanie wektoryzatora przy użyciu kreatora, ale możesz przetestować własny indeks, dostosowując nazwy pól i parametry zapytania.
Wysyłanie żądania za pomocą funkcji Dokumenty — wyszukiwanie postu (interfejs API REST). Zastąp nazwę usługi, nazwę indeksu i token dostępu własnymi wartościami.
### Test a vectorizer with a vector query
POST https://my-search-service.search.windows.net/indexes/vector-nasa-ebook-txt/docs/search?api-version=2026-10-01 HTTP/1.1
Content-Type: application/json
Authorization: Bearer <your-access-token> // For API keys, replace this line with api-key: <your-query-api-key>
{
"count": true,
"select": "title, chunk",
"vectorQueries": [
{
"kind": "text",
"text": "what cloud formations exist in the troposphere",
"fields": "text_vector",
"k": 3,
"exhaustive": true
}
]
}
Kluczowe punkty:
"kind": "text"informuje aparat wyszukiwania, że dane wejściowe są ciągiem tekstowym i aby użyć wektoryzatora skojarzonego z polem wyszukiwania."text"to ciąg tekstowy w języku naturalnym do wektoryzacji."fields": "text_vector"to nazwa pola używanego w zapytaniach. Jeśli używasz przykładowego indeksu utworzonego przez kreatora, wygenerowane pole wektora ma nazwętext_vector."exhaustive": truePomija graf HNSW i wykonuje wyszukiwanie siłowe we wszystkich wektorach. To ustawienie jest przydatne do testowania dokładności, ale jest wolniejsze niż domyślne przybliżone wyszukiwanie. Usuń ten parametr w zapytaniach produkcyjnych, aby uzyskać lepszą wydajność.Zapytanie nie ustawia żadnych właściwości wektoryzatora. Aparat wyszukiwania odczytuje je automatycznie z profilu wektora przypisanego do pola.
Jeśli wektoryzator jest poprawnie skonfigurowany, odpowiedź zwraca pasujące dokumenty sklasyfikowane według podobieństwa. Należy uzyskać trzy wyniki (k: 3), z których pierwsza jest najbardziej odpowiednia.
{
"@odata.count": 3,
"value": [
{
"@search.score": 0.66195244,
"chunk": "Cloud Shadow\tGermany\nIn November 2012, the Earth Observing...",
"title": "page-25.txt"
},
... // Trimmed for brevity
]
}
Rozwiązywanie problemów
Jeśli wektoryzator nie działa zgodnie z oczekiwaniami, zacznij od typowej tabeli błędów, a następnie sprawdź dzienniki diagnostyczne, aby uzyskać więcej szczegółów.
Typowe błędy
W poniższej tabeli wymieniono typowe błędy wektoryzatora i sposób ich rozwiązywania.
| Error | Przyczyna | Rezolucja |
|---|---|---|
| Błąd uwierzytelniania (401/403) | Nieprawidłowy klucz interfejsu API lub brakujące przypisanie roli RBAC dla modelu osadzania. | Sprawdź klucz interfejsu API lub upewnij się, że tożsamość usługi IQ rozwiązania Foundry ma Cognitive Services OpenAI User rolę w zasobie Azure OpenAI. |
| Niezgodność wymiarów | Model wektoryzatora tworzy osadzanie z inną liczbą wymiarów niż oczekiwano pola wektorowego. | Upewnij się, że właściwość dimensions w polu wektorowym jest zgodna z wymiarami wyjściowymi modelu osadzania (na przykład 1536 dla text-embedding-ada-002). |
| Ograniczanie szybkości (429) | Dostawca modelu osadzania ogranicza żądania. | Przejrzyj limity przydziału usługi Azure OpenAI i rozważ zwiększenie alokacji tokenów na minutę (TPM) lub zmniejszenie rozmiaru partii. |
| Nie znaleziono wektoryzatora | Profil wektorowy odwołuje się do nazwy wektoryzatora, która nie istnieje w indeksie. | Upewnij się, że właściwość vectorizer w profilu wektora zgadza się z name wektoryzatorem w tablicy vectorizers. |
| Puste wyniki | Konwersja tekstu na wektor powiodła się, ale zapytanie nie zwraca żadnych wyników. | Sprawdź, fields czy parametr w zapytaniu wektorowym jest zgodny z nazwą pola wektora z możliwością wyszukiwania. Zwiększ k, aby uzyskać więcej wyników. |
Sprawdzanie dzienników
Jeśli włączono rejestrowanie diagnostyczne dla usługi Foundry IQ, uruchom następujące zapytanie Kusto, aby potwierdzić wykonywanie zapytań dla pola wektorowego.
OperationEvent
| where TIMESTAMP > ago(30m)
| where Name == "Query.Search" and AdditionalInfo["QueryMetadata"]["Vectors"] has "TextLength"
Najlepsze rozwiązania
Użyj tożsamości zarządzanej zamiast kluczy interfejsu API w środowisku produkcyjnym. Tożsamości zarządzane są bezpieczniejsze i unikają potrzeby rotacji kluczy. Aby uzyskać więcej informacji, zobacz Konfigurowanie usługi Foundry IQ w celu nawiązania połączenia przy użyciu tożsamości zarządzanej.
Wdróż model embeddingów w tym samym regionie co usługa Foundry IQ. Kolokacja zmniejsza opóźnienie i zwiększa szybkość transferu danych między usługami. Wektoryzatory są dostępne we wszystkich regionach, w których jest dostępna funkcja IQ usługi Foundry, ale dostępność modelu zależy od dostawcy.
Użyj oddzielnych wdrożeń tego samego modelu osadzania na potrzeby indeksowania i zapytań. Wdrożenia dedykowane umożliwiają niezależne przydzielanie limity TPM dla każdego obciążenia i ułatwiają identyfikowanie źródeł ruchu.
Monitoruj przydział TPM w Azure OpenAI. Jeśli osiągniesz limit TPM, przejrzyj limity przydziału i rozważ złożenie żądania wyższego limitu za pomocą zgłoszenia do działu pomocy technicznej.
Zapoznaj się z najlepszymi rozwiązaniami dotyczącymi umiejętności osadzania w usłudze Azure OpenAI. Te same wskazówki dotyczą wektoryzatora azure OpenAI.