ИИ-коннектор

ИИ-коннектор позволяет подключить приложения в кластере к AI Gateway для работы с ИИ-моделями. Коннектор создает API-ключ и автоматически сохраняет его в секретах Kubernetes. Вы можете подключить секрет к приложению через переменную окружения или файл.

Запросы с ключом коннектора тарифицируются по правилам AI Gateway.

Создание ключа

Создать ключ можно только для запущенного кластера.

1. В разделе «Kubernetes» откройте нужный кластер.

2. Перейдите во вкладку «Управление» и нажмите на кнопку «Подключить» напротив «ИИ-коннектор».

3. Нажмите «Создать ключ».

4. Укажите название, комментарий и проект. При необходимости задайте срок действия ключа.

5. Выберите один или несколько неймспейсов, в которых приложения будут использовать ключ.

6. Создайте ключ.

После создания откроется окно со значением ключа и адресом AI Gateway. Значение показывается в панели только один раз, поэтому сохраните его, если планируете использовать вне секрета кластера. Для подключения приложения через секрет копировать значение ключа не нужно.

Коннектор создаст в каждом выбранном неймспейсе секрет типа Opaque с ключом в поле api-key. Пока секреты создаются, ключ в списке отображается как обрабатываемый. После подтверждения со стороны кластера он станет активным.

Имя секрета отображается в списке ключей коннектора. Скопируйте его — оно понадобится для настройки приложения. У одного ключа имя секрета одинаковое во всех выбранных неймспейсах.

Подключение ключа к приложению

Приложение и секрет должны находиться в одном неймспейсе. В зависимости от того, как приложение получает ключ, используйте один из двух способов:

• Через переменную окружения. В манифесте контейнера добавьте переменную в секцию env и укажите в valueFrom.secretKeyRef имя секрета и поле api-key. Значение ключа будет передано в переменную с именем, которое использует приложение, например OPENAI_API_KEY.

• Через файл. Добавьте секрет в секцию volumes и подключите его к контейнеру через volumeMounts. Ключ будет доступен в файле api-key внутри каталога монтирования. Например, при монтировании в /etc/ai-gateway приложение должно читать файл /etc/ai-gateway/api-key.

В настройках приложения также укажите базовый адрес API — https://api.timeweb.ai/v1. Если приложение поддерживает переменную OPENAI_BASE_URL, адрес можно передать через нее.

Перегенерация ключа

Управлять ключом можно в разделе «ИИ-коннектор» во вкладке «Управление» кластера. На странице ключей AI Gateway он также отображается, но изменить или удалить его там нельзя.

Для перегенерации ключа нажмите на три точки рядом с нужным ключом и выберите «Перегенерировать». В открывшемся окне также можно изменить список неймспейсов: в добавленных секрет будет создан, из исключенных — удален.

После перегенерации коннектор запишет новое значение в секреты. Имя секрета останется прежним, поэтому менять ссылку на него в манифесте не нужно. Новое значение ключа показывается в панели только один раз.

Если ключ передается через переменную окружения, после обновления секрета перезапустите поды приложения. Например, для приложения, развернутого через Deployment:

    

      

    
    kubectl rollout restart deployment/my-app -n default
  

Замените my-app и default на имя Deployment и неймспейс вашего приложения.

Срок действия ключа

Если при создании ключа задан срок действия, после его истечения AI Gateway перестанет принимать запросы с этим ключом. Секрет при этом останется в кластере.

Срок действия отображается в списке ключей коннектора. При приближении даты он подсвечивается желтым, за неделю до истечения и после него — красным.

Удаление ключа

В разделе «ИИ-коннектор» нажмите на три точки рядом с нужным ключом и выберите действие «Удалить».

Ключ будет отозван, а связанные с ним секреты удалены из всех неймспейсов. Приложения, которые использовали этот ключ, потеряют доступ к AI Gateway.

Пример использования

Рассмотрим базовый пример подключения к AI Gateway из кластера. Создадим временный под с образом python:3.12-slim. Скрипт внутри пода получит ключ из секрета, отправит запрос к модели и выведет ответ в логи. Устанавливать дополнительные пакеты или собирать собственный образ не нужно.

Приложение и секрет должны находиться в одном неймспейсе. В примере используется неймспейс default и секрет ai-key-test-dfffcae0. Замените имя секрета на скопированное из панели.

Создайте файл ai-gateway-check.yaml:

    

      

    
    apiVersion: v1
kind: Pod
metadata:
  name: ai-gateway-check
  namespace: default
spec:
  restartPolicy: Never
  containers:
    - name: check
      image: python:3.12-slim
      env:
        - name: AI_GATEWAY_API_KEY
          valueFrom:
            secretKeyRef:
              name: ai-key-test-dfffcae0
              key: api-key
      command: ["python", "-c"]
      args:
        - |
          import json
          import os
          import urllib.request

          payload = json.dumps({
              "model": "openai/gpt-4.1-mini",
              "messages": [{"role": "user", "content": "Ответь одним словом: работает?"}],
              "max_tokens": 20,
          }).encode("utf-8")

          request = urllib.request.Request(
              "https://api.timeweb.ai/v1/chat/completions",
              data=payload,
              headers={
                  "Authorization": "Bearer " + os.environ["AI_GATEWAY_API_KEY"],
                  "Content-Type": "application/json",
              },
          )

          with urllib.request.urlopen(request, timeout=60) as response:
              result = json.load(response)

          print(result["choices"][0]["message"]["content"])
  

В примере указана модель openai/gpt-4.1-mini. При необходимости замените ее на доступную модель из списка AI Gateway.

После того как ключ станет активным, убедитесь, что секрет создан:

    

      

    
    kubectl get secret ai-key-test-dfffcae0 -n default
  

Запустите создание пода:

    

      

    
    kubectl apply -f ai-gateway-check.yaml
  

Дождитесь завершения выполнения пода:

    

      

    
    kubectl get pod ai-gateway-check -n default
  

Посмотрите ответ модели в логах:

    

      

    
    kubectl logs ai-gateway-check -n default
  

При успешном запросе под перейдет в статус Completed, а в логах будет ответ модели. После проверки удалите под:

    

      

    
    kubectl delete pod ai-gateway-check -n default