Konfiguracja AIConfiguration

Plik aiconfiguration.json stanowi centralny element konfiguracji AI Proxy. Definiuje połączenia z dostawcami AI, dostępne modele oraz strategie ich wykorzystania. To właśnie w nim określasz, które modele są udostępniane w WEBCON, w jakiej kolejności mają być wybierane (priority) oraz jakie parametry połączenia są używane do komunikacji z poszczególnymi dostawcami.

W tym przewodniku przedstawiono pełną strukturę pliku konfiguracyjnego wraz z przykładami dla trzech obsługiwanych dostawców: Google Vertex AI, OpenAI oraz Azure AI Foundry. Każda sekcja została opisana wraz z wyjaśnieniem parametrów i przykładowymi wartościami. Możesz wykorzystać kompletną konfigurację jako punkt wyjścia albo uwzględnić tylko te elementy, które odpowiadają Twoim potrzebom.

Ważne dla trybu Self-hosted

W trybie Self-hosted wartości w sekcji ProviderConfiguration zawierają rzeczywiste klucze API, a nie nazwy sekretów z Key Vault. Z tego powodu nie należy commitować tego pliku do repozytorium.

Czego dowiesz się z tego przewodnika

• jak definiować połączenia z dostawcami AI (ProviderConnections),
• jak konfigurować dostępne modele i ich priorytety (ProviderModels),
• jak przypisywać modele do konretnych funkcji WEBCON (MethodTypesConfiguration),
• jakie parametry są wymagane dla poszczególnych dostawców,
• jak skonfigurować strategie failover między dostawcami.

Struktura konfiguracji

Plik składa się z trzech głównych sekcji:

1. ProviderConnections - definicje połączeń z dostawcami AI,
2. ProviderModels - lista dostępnych modeli,
3. MethodTypesConfiguration - przypisanie modeli do poszczególnych funkcji.

Przykład kompletnej konfiguracji

Poniżej znajduje się przykładowa kompletna konfiguracja obejmująca trzech dostawców AI: Azure AI Foundry, Google Vertex AI oraz OpenAI.

{
  "ProviderConnections": {
    "AzureFoundry": {
      "Description": "Azure AiFoundry Connector Provider",
      "Type": "AzureAi",
      "ProviderConfiguration": {
        "ApiKey": "your-azure-api-key-here",
        "Endpoint": "https://your-endpoint.openai.azure.com/"
      }
    },
    "GoogleVertex": {
      "Description": "Google Connector Provider",
      "Type": "Gemini",
      "ProviderConfiguration": {
        "ApiKey": "your-google-api-key-here",
        "ServiceAccount": "{\"type\":\"service_account\",\"project_id\":\"your-project\"...}",
        "ProjectId": "your-project-id",
        "Region": "us-central1",
        "BucketName": "your-bucket-name",
        "DocumentationProcessBuilderRagCorpus": "your-corpus-id"
      }
    },
    "OpenAi": {
      "Description": "OpenAi Connector Provider",
      "Type": "OpenAi",
      "ProviderConfiguration": {
        "ApiKey": "sk-your-openai-api-key-here"
      }
    }
  },

  "ProviderModels": [
    {
      "ConnectionName": "GoogleVertex",
      "Priority": 4,
      "Name": "Gemini 2.0-flash-lite-001",
      "Description": "",
      "TextModel": {
        "ModelName": "gemini-2.0-flash-lite-001"
      },
      "ImageModel": {
        "ModelName": "imagen-3.0-fast-generate-001"
      },
      "AudioModel": {
        "ModelName": "gemini-2.0-flash-lite-001"
      },
      "EmbeddingModel": {
        "ModelName": "gemini-embedding-001"
      }
    },
    {
      "ConnectionName": "GoogleVertex",
      "Priority": 3,
      "Name": "Vertex gemini 2.5-flash-lite",
      "Description": "",
      "TextModel": {
        "ModelName": "gemini-2.5-flash-lite"
      },
      "ImageModel": {
        "ModelName": "imagen-3.0-fast-generate-001"
      },
      "AudioModel": {
        "ModelName": "gemini-2.5-flash-lite"
      },
      "EmbeddingModel": {
        "ModelName": "gemini-embedding-001"
      }
    },
    {
      "ConnectionName": "GoogleVertex",
      "Priority": 2,
      "Name": "Vertex gemini 2.5-flash",
      "Description": "",
      "TextModel": {
        "ModelName": "gemini-2.5-flash"
      },
      "ImageModel": {
        "ModelName": "imagen-3.0-fast-generate-001"
      },
      "AudioModel": {
        "ModelName": "gemini-2.5-flash"
      },
      "EmbeddingModel": {
        "ModelName": "gemini-embedding-001"
      }
    },
    {
      "ConnectionName": "OpenAi",
      "Priority": 1,
      "Name": "OpenAi BasicTier",
      "Description": "",
      "TextModel": {
        "ModelName": "gpt-4o-mini-2024-07-18"
      },
      "ImageModel": {
        "ModelName": "gpt-4o-mini-2024-07-18"
      },
      "AudioModel": {
        "ModelName": "whisper-01"
      },
      "EmbeddingModel": {
        "ModelName": "text-embedding-3-small"
      }
    }
  ],

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

Wyjaśnienie sekcji

ProviderConnections

Sekcja zawierająca definicje połączeń z dostawcami AI. Każdy wpis obejmuje:

• Type - typ dostawcy: AzureAi, Gemini, OpenAi,
• ProviderConfiguration - parametry połączenia, takie jak klucze API i inne ustawienia wymagane przez danego dostawcę.

wskazówka

Z konfiguracji możesz usunąć nieużywanych dostawców. Na przykład, jeśli korzystasz wyłącznie z Google Vertex AI, możesz pominąć sekcje AzureFoundry i OpenAi.

ProviderModels

Sekcja zawierająca listę dostępnych modeli AI. Każdy model obejmuje:

• ConnectionName - nazwę połączenia zdefiniowanego w sekcji ProviderConnections,
• Priority - priorytet modelu; wyższa wartość oznacza większe pierwszeństwo przy automatycznym wyborze,
• Name - unikalną nazwę modelu,
• TextModel, ImageModel, AudioModel, EmbeddingModel - nazwy modeli wykorzystywanych do poszczególnych typów operacji.

MethodTypesConfiguration

Sekcja odpowiadająca za mapowanie typów operacji na modele. Określa, które modele będą używane w ramach poszczególnych funkcji, na przykład:

• ConciergePrompt - generowanie odpowiedzi na pytania użytkowników,
• ConciergeExecuteTool - wykonywanie narzędzi przez AI.

Kolejność modeli w tablicy określa preferencję ich użycia. AI Proxy najpierw spróbuje skorzystać z pierwszego modelu na liście, a jeśli będzie on niedostępny, przejdzie do kolejnego.

Podstawowe kroki konfiguracji

1. Przygotuj klucze API

Przygotuj dane dostępowe wymagane przez wybranych dostawców AI:

• Google Vertex AI - plik Service Account w formacie JSON, identyfikator projektu (Project ID) oraz region,
• OpenAI - API Key rozpoczynający się od sk-,
• Azure OpenAI - API Key oraz Endpoint URL.

2. Edytuj plik aiconfiguration.json

Uzupełnij odpowiednie wartości w sekcji ProviderConfiguration:

"ProviderConfiguration": {
  "ApiKey": "sk-your-actual-api-key-here"
}

3. Zapisz plik konfiguracyjny

Przed uruchomieniem upewnij się, że:

• plik JSON ma poprawną składnię, bez brakujących przecinków i nawiasów,
• wszystkie wymagane klucze API oraz parametry połączenia zostały uzupełnione,
• plik aiconfiguration.json znajduje się w tym samym katalogu co docker-compose.yml.

4. Uruchom kontener

docker-compose up -d

Rozwiązywanie problemów

Błąd: Invalid JSON format

# Sprawdź poprawność JSON online lub edytorem
# Upewnij się, że:
# - Wszystkie cudzysłowy są podwójne "
# - Przecinki między elementami (ale nie po ostatnim)
# - Wszystkie nawiasy {} i [] są zamknięte

Błąd: Authentication failed

Możliwe przyczyny:

• klucz API jest nieprawidłowy,
• klucz wygasł lub został unieważniony,
• adres endpointu jest niepoprawny (dla Azure).

Rozwiązanie:

# Sprawdź logi kontenera
docker-compose logs ai-proxy

# Wygeneruj nowy klucz API u dostawcy
# Zaktualizuj aiconfiguration.json
# Zrestartuj kontener
docker-compose restart ai-proxy

Model nie jest używany

Możliwe przyczyny:

• wartość ConnectionName nie odpowiada nazwie zdefiniowanej w sekcji ProviderConnections,
• wskazany model nie istnieje u dostawcy, np. z powodu literówki w ModelName,
• wartość Name w sekcji MethodTypesConfiguration nie odpowiada wartości Name zdefiniowanej w ProviderModels.

Rozwiązanie: Sprawdź, czy nazwy we wszystkich sekcjach są ze sobą zgodne. Muszą być identyczne, łącznie z wielkością liter.