---
title: "ИИ-коннектор"
---

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

> Полный индекс документации для ИИ-агентов: [llms.txt](https://timeweb.cloud/llms.txt).

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

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

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

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

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

![Настройка ИИ-коннектора](https://content.timeweb.com/assets/a57fd5eb-6515-4262-b9d0-9753b6cd7a5b.png?width=2014&height=1880)

3.  Нажмите «Создать ключ».
    
4.  Укажите название, комментарий и проект. При необходимости задайте срок действия ключа.
    
5.  Выберите один или несколько неймспейсов, в которых приложения будут использовать ключ.
    
6.  Создайте ключ.
    

![Создание ключа](https://content.timeweb.com/assets/904ae1a5-efdb-4d03-b230-c32ae2198731.png?width=2722&height=1544)

После создания откроется окно со значением ключа и адресом 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 он также отображается, но изменить или удалить его там нельзя.

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

![Перегенерация ключа](https://content.timeweb.com/assets/efe09872-8a9f-4a0f-8527-761df1b1a468.png?width=918&height=580)

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

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

```shell
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`:

```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.

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

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

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

```shell
kubectl apply -f ai-gateway-check.yaml
```

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

```shell
kubectl get pod ai-gateway-check -n default
```

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

```shell
kubectl logs ai-gateway-check -n default
```

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

```shell
kubectl delete pod ai-gateway-check -n default
```