Konfiguracja AIConfiguration

Plik aiconfiguration.json oraz jego warianty środowiskowe (np. aiconfiguration.Staging.json, aiconfiguration.Production.json) zawierają konfigurację połączeń z dostawcami AI, definicje modeli oraz mapowanie typów operacji na konkretne modele. Ten rozdział wyjaśnia strukturę, sposób przygotowania i walidacji konfiguracji.

Celem jest opisanie struktury i kluczowych sekcji: ProviderConnections, ProviderModels i MethodTypesConfiguration oraz dostarczenie przykładów oraz listy kontrolnej do szybkiej walidacji konfiguracji.

Wyjaśnienie kluczowych sekcji

ProviderConnections

Sekcja ProviderConnections zawiera listę skonfigurowanych połączeń z dostawcami AI. Każdy wpis zawiera:

• Description - opis połączenia,
• Type - typ dostawcy (np. Gemini, OpenAi, Azure),
• ProviderConfiguration - obiekt konfiguracyjny zawierający nazwy sekretów Key Vault (NIE rzeczywiste sekrety).

informacja

Wartości w ProviderConfiguration to nazwy sekretów Key Vault, a nie faktyczne klucze API. W trybie Self-hosted (przy braku Azure Key Vault) ustawiamy tutaj rzeczywisty sekret.

ProviderModels

Sekcja ProviderModels to tablica definicji modeli mapowanych do ConnectionName. Każdy wpis zawiera:

• ConnectionName - nazwa połączenia z ProviderConnections,
• Priority - priorytet modelu (wyższa wartość = wyższy priorytet przy wyborze modelu),
• Name - unikalna nazwa modelu (używana w mapowaniu MethodTypesConfiguration),
• TextModel - obiekt zawierający ModelName dla operacji tekstowych,
• ImageModel (opcjonalnie) - obiekt zawierający ModelName dla operacji obrazowych. Wymagany przy generowaniu obrazów,
• AudioModel (opcjonalnie) - obiekt zawierający ModelName dla operacji audio. Wymagany do akcji AudioTranscrabie,
• EmbeddingModel (opcjonalnie) - obiekt zawierający ModelName dla operacji embedding. Wymagany przy generowaniu embeddingów.

MethodTypesConfiguration

Sekcja MethodTypesConfiguration mapuje logiczne typy metod (np. ConciergePrompt, ConciergeExecuteTool, AgentPrompt) na uporządkowane tablice nazw modeli z ProviderModels. Określa to preferowane modele dla każdego typu operacji.

Kolejność w tablicy ma znaczenie - aplikacja próbuje użyć pierwszego modelu, a w przypadku niedostępności przechodzi do następnego.

Przykład konfiguracji

Poniżej znajduje się przykład bazujący na aiconfiguration.Staging.json:

{
  "ProviderConnections": {
    "GoogleVertex": {
      "Description": "Google Connector Provider",
      "Type": "Gemini",
      "ProviderConfiguration": {
        "ApiKey": "AiGeminiTestEnvironment",
        "ServiceAccount": "AiVertexAiServiceAccountJson",
        "ProjectId": "AiVertexAiProjectId",
        "Region": "AiVertexAiRegion",
        "BucketName": "AiGoogleCloudBucketName"
      }
    },
    "OpenAi": {
      "Description": "OpenAi Connector Provider",
      "Type": "OpenAi",
      "ProviderConfiguration": {
        "ApiKey": "AiOpenAiTestEnvironment"
      }
    }
  },

  "ProviderModels": [
    {
      "ConnectionName": "GoogleVertex",
      "Priority": 4,
      "Name": "Gemini 2.0-flash-lite-001",
      "TextModel": { "ModelName": "gemini-2.0-flash-lite-001" }
    },
    {
      "ConnectionName": "OpenAi",
      "Priority": 1,
      "Name": "OpenAi BasicTier",
      "TextModel": { "ModelName": "gpt-4o-mini-2024-07-18" },
      "ImageModel": { "ModelName": "dall-e-3" }
    }
  ],

  "MethodTypesConfiguration": {
    "ConciergePrompt": [ 
      "Gemini 2.0-flash-lite-001", 
      "Vertex gemini 2.5-flash-lite" 
    ],
    "ConciergeExecuteTool": [ 
      "Gemini 2.0-flash-lite-001", 
      "Vertex gemini 2.5-flash" 
    ],
    "AgentPrompt": [
      "OpenAi BasicTier"
    ]
  }
}

Lista kontrolna przygotowania (kroki dla supportu)

Krok 1: Walidacja lokalizacji i nazwy pliku

• Potwierdź, że edytujesz właściwy plik dla środowiska: aiconfiguration.json, aiconfiguration.Staging.json lub aiconfiguration.Production.json.

Krok 2: Potwierdzenie braku sekretów w jawnym tekście

• Wszystkie wartości sekretów w ProviderConfiguration muszą być nazwami sekretów w Key Vault (np. AiOpenAiTestEnvironment), a nie rzeczywistymi kluczami API.
• NIGDY nie umieszczaj faktycznych kluczy API w pliku konfiguracyjnym.

Krok 3: Weryfikacja istnienia sekretów w Key Vault

• Dla każdej nazwy Key Vault wymienionej w konfiguracji sprawdź, czy instancja Key Vault zawiera sekret o oczekiwanej nazwie.
• Typowe klucze Key Vault do weryfikacji (z przykładu):
  • AiGeminiTestEnvironment
  • AiVertexAiServiceAccountJson
  • AiVertexAiProjectId
  • AiOpenAiTestEnvironment

Krok 4: Sprawdzenie spójności ProviderModels

• Upewnij się, że każdy ProviderModel.ConnectionName odpowiada kluczowi w ProviderConnections.
• Potwierdź, że kolejność Priority jest zamierzona (wyższa wartość = wyższy priorytet przy wyborze modeli).
• Zweryfikuj poprawność wartości ModelName dla danego dostawcy (np. prawidłowa konwencja nazewnictwa dla Vertex/OpenAI).

Krok 5: Walidacja MethodTypesConfiguration

• Upewnij się, że wartości Name modeli wymienione tutaj dokładnie odpowiadają ciągom ProviderModels[].Name.
• Kolejność określa preferencje zapasowe - potwierdź, że kolejność odzwierciedla pożądane zachowanie.
• Sprawdź, czy wszystkie typy metod używane przez aplikację mają odpowiednie mapowanie.

Krok 6: Kontrola JSON

• Uruchom linter/walidator JSON, aby upewnić się, że plik jest poprawnie sformatowany.
• Sprawdź poprawność przecinków, nawiasów i cudzysłowów.

Krok 7: Wdrożenie / przeładowanie aplikacji

• Po zmianach aplikacja wymaga przeładowania konfiguracji poprzez ponowne uruchomienie.
• Zweryfikuj pipeline wdrożeniowy lub procedurę restartu usługi w danym środowisku.

Typowe błędy i rozwiązywanie problemów

Użycie rzeczywistych kluczy API w aiconfiguration zamiast nazw sekretów Key Vault.

Objawy:

• ryzyko bezpieczeństwa (sekrety trafiają do repozytorium),
• brak możliwości centralnego zarządzania sekretami.

Rozwiązanie:

• zastąp wartość w jawnym tekście nazwą sekretu z Key Vault,
• przechowuj rzeczywisty klucz w Key Vault.

---

Literówka w ProviderModels.Name w nazwie modelu powoduje niedopasowanie w MethodTypesConfiguration.

Objawy:

• wybór modelu kończy się niepowodzeniem lub działa nieoczekiwanie,
• błędy w logach o braku modelu.

Rozwiązanie:

• zapewnij dokładne dopasowanie ciągów znaków,
• ponownie wdróż / przeładuj konfigurację.

---

ConnectionName nie odpowiada kluczowi ProviderConnections.

Objawy:

• wybór modelu nie może znaleźć ustawień dostawcy,
• błędy inicjalizacji connectora.

Rozwiązanie:

• popraw ConnectionName lub dodaj wpis dostawcy w ProviderConnections.

---

Użycie niewłaściwej wartości Type dla dostawcy (np. Gemini vs Vertex, gdy connector oczekuje konkretnej wartości).

Objawy:

• fabryka connectorów nie może skonstruować dostawcy,
• błędy inicjalizacji podczas startu aplikacji.

Rozwiązanie:

• użyj typu dostawcy obsługiwanego przez implementację connectora,
• w razie wątpliwości sprawdź kod Modules/AiConnector.

Runbook supportu (krok po kroku)

1. Otwórz plik konfiguracyjny specyficzny dla środowiska (np. aiconfiguration.Staging.json).
2. Uruchom walidację JSON.
3. Sprawdź każdą wartość właściwości ProviderConfiguration względem wpisów w Key Vault.
4. Zweryfikuj nazwy modeli i mapowania method-type pod kątem literówek.
5. Jeśli wymagane są zmiany, zaktualizuj plik JSON w gałęzi repozytorium dla środowiska i utwórz PR.
6. Po merge upewnij się, że pipeline wdrożeniowy działa i usługa się restartuje (lub uruchom restart ręcznie).
7. Monitoruj logi pod kątem błędów: dostęp do Key Vault, inicjalizacja connectora, ostrzeżenia wyboru modelu.

Najlepsze praktyki

• Zawsze używaj Key Vault - nie przechowuj sekretów w plikach konfiguracyjnych.
• Dokumentuj zmiany - dodawaj komentarze o zmianach w konfiguracji w commit message.
• Testuj w staging - testuj zmiany w konfiguracji na środowisku staging.
• Monitoruj po wdrożeniu - sprawdzaj logi i metryki po każdej zmianie w konfiguracji.
• Wersjonowanie - utrzymuj historię zmian w systemie kontroli wersji.
• Backup - zachowuj kopie zapasowe działających konfiguracji.