AI Gateway를 사용할 때 다음과 같은 문제가 발생할 수 있습니다.

OpenShift 권한 문제#

OpenShift에 AI Gateway를 배포할 때 OpenShift 보안 모델 때문에 권한 오류가 발생할 수 있습니다.

/tmp의 읽기 전용 파일 시스템#

AI Gateway는 /tmp에 기록합니다. 그러나 보안이 제한된 OpenShift 환경에 따라 /tmp가 읽기 전용일 수 있습니다.

이 문제를 해결하려면 새 EmptyDir 볼륨을 만들어 /tmp에 마운트합니다. 다음 중 한 가지 방법을 사용합니다.

• 명령줄에서:

  oc set volume <object_type>/<name> --add --name=tmpVol --type=emptyDir --mountPoint=/tmp
  

• values.yaml에서:

  volumes:
  - name: tmp-volume
    emptyDir: {}
  
  volumeMounts:
  - name: tmp-volume
    mountPath: "/tmp"
  

HuggingFace 모델#

기본적으로 AI Gateway는 HuggingFace 모델을 캐시하는 데 /home/aigateway/.hf를 사용하며, 보안이 제한된 OpenShift 환경에서는 이 경로에 기록할 수 없을 수 있습니다. 다음과 같은 권한 오류가 발생할 수 있습니다.

[Errno 13] Permission denied: '/home/aigateway/.hf/...'

이 문제를 해결하려면 HF_HOME 환경 변수를 쓰기 가능한 위치로 설정합니다. /var/tmp/huggingface 또는 컨테이너가 쓸 수 있는 다른 디렉터리를 사용할 수 있으며, 다음 중 한 가지 방법을 사용합니다.

• values.yaml에서:

  extraEnvironmentVariables:
    - name: HF_HOME
      value: /var/tmp/huggingface  # Use any writable directory
  

• Helm upgrade 명령에서:

  --set "extraEnvironmentVariables[0].name=HF_HOME" \
  --set "extraEnvironmentVariables[0].value=/var/tmp/huggingface"  # Use any writable directory
  

이 구성은 OpenShift 보안 제약을 지키면서 AI Gateway가 HuggingFace 모델을 올바르게 캐시하도록 합니다. 선택하는 정확한 디렉터리는 사용하는 OpenShift 구성과 보안 정책에 따라 달라질 수 있습니다.

볼륨 마운트에 가려진 토크나이저 캐시#

AI Gateway 이미지에 미리 캐시된 토크나이저 파일이 다음 경우 볼륨 마운트에 가려질 수 있습니다.

• 코드 완성 요청이 500 오류를 반환합니다.
• AI Gateway 로그에 huggingface.co에서 Salesforce/codegen2-16B를 다운로드하려는 transformers/utils/hub.py의 OSError가 표시됩니다.

자체 호스팅 AI Gateway 이미지(self-hosted-vX.Y.Z-ee)는 HF_HUB_OFFLINE=true를 설정하고 빌드 시점에 토크나이저를 미리 캐시하므로, 런타임에 huggingface.co로 네트워크 접근이 발생하지 않아야 합니다. 네트워크 접근이 발생한다면 Helm values의 빈 디렉터리가 /home/aigateway/.hf 위에 마운트되어 캐시된 파일을 덮어썼을 수 있습니다.

huggingface.co에 대한 외부 송신 접근을 허용해 이 문제를 해결하려고 하지 않습니다. 대신 문제를 진단하려면 AI Gateway 파드에서 다음을 실행합니다.

ls -la /home/aigateway/.hf/hub/ 2>/dev/null || echo "NO_CACHE_DIR"
env | grep -E '^(HF_|TRANSFORMERS_)'

캐시 디렉터리가 없거나 비어 있다면 다음을 수행합니다.

1. values.yaml에서 /home/aigateway/.hf 또는 HF_HOME으로 설정한 경로를 대상으로 하는 volumeMounts가 있는지 확인합니다.
2. 마운트를 제거하거나 이미지에 내장된 캐시와 겹치지 않는 디렉터리로 다시 지정합니다.

자체 서명 인증서 오류#

AI Gateway가 사용자 지정 인증 기관(CA)이나 자체 서명 인증서로 서명된 인증서를 사용하는 GitLab 인스턴스 또는 모델 엔드포인트에 연결하려고 하면 다음 오류가 발생할 수 있습니다.

[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain

이 문제를 해결하려면 자체 서명 SSL 인증서로 GitLab 인스턴스 또는 모델 엔드포인트에 연결을 참고합니다.

토큰 생성 실패#

GitLab Duo Chat 같은 기능을 사용할 때 Token creation failed 오류가 발생한다면 AI Gateway에 AIGW_SELF_SIGNED_JWT__SIGNING_KEY와 AIGW_SELF_SIGNED_JWT__VALIDATION_KEY 환경 변수가 설정되어 있지 않을 수 있습니다.

AI Gateway가 수명이 짧은 사용자 JWT를 발급하려면 이 키가 필요합니다. 이 키가 없으면 AI Gateway가 토큰에 서명할 수 없으며, 이로 인해 JWK 역직렬화 실패가 발생합니다.

이 문제를 해결하려면 다음을 수행합니다.

1. 필요한 키를 생성합니다.

   openssl genrsa -out aigw_signing.key 2048
   openssl genrsa -out aigw_validation.key 2048
   

2. 환경 변수로 전달해 AI Gateway 컨테이너에 키를 추가합니다.

   -e AIGW_SELF_SIGNED_JWT__SIGNING_KEY="$(cat aigw_signing.key)" \
   -e AIGW_SELF_SIGNED_JWT__VALIDATION_KEY="$(cat aigw_validation.key)"
   

3. AI Gateway 컨테이너를 다시 시작합니다.

PEM 파일을 로드할 때 발생하는 SSL 인증서 오류#

PEM 파일을 Docker 컨테이너에 로드하는 중 JWKError라는 오류가 발생한다면 SSL 인증서 오류를 해결해야 할 수 있습니다.

이 문제를 해결하려면 다음 환경 변수를 사용해 Docker 컨테이너에 적절한 인증서 번들 경로를 설정합니다.

• SSL_CERT_FILE=/path/to/ca-bundle.pem
• REQUESTS_CA_BUNDLE=/path/to/ca-bundle.pem

/path/to/ca-bundle.pem을 인증서 번들의 경로로 바꿉니다.

오프라인 GitLab 인스턴스로 과금 이벤트를 보낼 때 발생하는 오류#

오프라인 환경에서 AI Gateway는 GitLab 인스턴스의 /api/v4/ai/billable_usage/events API 엔드포인트로 이벤트를 보냅니다. 요청이 실패하면 AI Gateway 로그에서 응답 상태를 확인합니다.

• 401: AIGW_BILLING_EVENT__API_KEY가 설정되지 않았거나 토큰이 유효하지 않습니다.
• 403: 토큰에 ai_features 범위가 없거나 서비스 계정에 속하지 않습니다.
• 404: local_billing_persistence 기능 플래그가 비활성화되어 있거나 GitLab 인스턴스가 오프라인 라이선스를 사용하지 않습니다.

자세한 내용은 GitLab 인스턴스로 과금 이벤트 보내기를 참고합니다.