자체 호스팅 모델 문제 해결

요약

문제 해결을 시작하기 전에 다음을 준비해야 합니다: GitLab Duo 문제 해결에 대한 자세한 정보는 다음을 참조하세요: 관리자가 자체 호스팅 모델 구성을 검증하는 데 도움이 되는 두 가지 디버깅 스크립트를 제공합니다.

히스토리

GitLab 17.1에서 ai_custom_model이라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화됩니다.
GitLab 17.6에서 GitLab Self-Managed에서 활성화되었습니다.
GitLab 17.6 이후에 GitLab Duo 애드온이 필요하도록 변경되었습니다.
GitLab 17.8에서 기능 플래그 ai_custom_model이 제거되었습니다.
GitLab 17.9에서 일반 제공됩니다.
GitLab 18.0에서 Premium을 포함하도록 변경되었습니다.

문제 해결을 시작하기 전에 다음을 준비해야 합니다:

gitlab-rails 콘솔에 접근할 수 있어야 합니다.
AI Gateway Docker 이미지에서 쉘을 엽니다.
다음의 엔드포인트를 알고 있어야 합니다:
- AI Gateway가 호스팅된 엔드포인트
- 모델이 호스팅된 엔드포인트
로깅 활성화하여 GitLab에서 AI Gateway로의 요청과 응답이 llm.log에 기록되는지 확인합니다.

GitLab Duo 문제 해결에 대한 자세한 정보는 다음을 참조하세요:

디버깅 스크립트 사용#

관리자가 자체 호스팅 모델 구성을 검증하는 데 도움이 되는 두 가지 디버깅 스크립트를 제공합니다.

GitLab에서 AI Gateway로의 연결을 디버그합니다. GitLab 인스턴스에서 Rake 태스크를 실행합니다:
```
gitlab-rake "gitlab:duo:verify_self_hosted_setup[<username>]"
```
선택 사항: 시트가 할당된 <username>을 포함합니다. 사용자 이름 파라미터를 포함하지 않으면 Rake 태스크는 루트 사용자를 사용합니다.

AI Gateway 설정을 디버그합니다. AI Gateway 컨테이너에서:

인증을 비활성화하여 AI Gateway 컨테이너를 다시 시작합니다:
```
-e AIGW_AUTH__BYPASS_EXTERNAL=true
```
이 설정은 문제 해결 명령이 시스템 교환 테스트를 실행하는 데 필요합니다. 문제 해결이 완료된 후 이 설정을 제거해야 합니다.

AI Gateway 컨테이너에서 다음을 실행합니다:

docker exec -it <ai-gateway-container> sh
poetry run troubleshoot [options]

troubleshoot 명령은 다음 옵션을 지원합니다:

옵션	기본값	예시	설명
`--endpoint`	`localhost:5052`	`--endpoint=localhost:5052`	AI Gateway 엔드포인트
`--model-family`	-	`--model-family=mistral`	테스트할 모델 패밀리. `mistral`, `mixtral`, `gpt`, `claude_3` 중 하나
`--model-endpoint`	-	`--model-endpoint=http://localhost:4000/v1`	모델 엔드포인트. vLLM에서 호스팅된 모델의 경우 `/v1` 접미사를 추가합니다.
`--model-identifier`	-	`--model-identifier=custom_openai/Mixtral-8x7B-Instruct-v0.1`	모델 식별자
`--api-key`	-	`--api-key=your-api-key`	모델 API 키

예시:

AWS Bedrock에서 실행 중인 claude_3 모델:

poetry run troubleshoot \
  --model-family=claude_3 \
  --model-identifier=bedrock/anthropic.claude-3-5-sonnet-20240620-v1:0

vLLM에서 실행 중인 mixtral 모델:

poetry run troubleshoot \
  --model-family=mixtral \
  --model-identifier=custom_openai/Mixtral-8x7B-Instruct-v0.1 \
  --api-key=your-api-key \
  --model-endpoint=http://<your-model-endpoint>/v1

문제 해결이 완료되면 AIGW_AUTH__BYPASS_EXTERNAL=true 없이 AI Gateway 컨테이너를 중지하고 재시작합니다.

Warning

프로덕션에서 인증을 우회해서는 안 됩니다.

명령의 출력을 확인하고 그에 따라 수정합니다.

두 명령이 모두 성공했지만 GitLab Duo Code Suggestions가 여전히 작동하지 않으면 이슈 트래커에 이슈를 제기합니다.

GitLab Duo 상태 확인이 작동하지 않음#

GitLab Duo에 대한 상태 확인을 실행할 때 AI Gateway에서 401 응답과 같은 오류가 발생할 수 있습니다.

해결하려면 먼저 GitLab Duo 기능이 올바르게 작동하는지 확인합니다. 예를 들어 GitLab Duo Chat에 메시지를 보냅니다.

이 방법이 작동하지 않으면 GitLab Duo 상태 확인의 알려진 문제로 인한 오류일 수 있습니다. 자세한 정보는 이슈 517097을 참조하세요.

GitLab이 모델에 요청할 수 있는지 확인#

GitLab Rails 콘솔에서 다음을 실행하여 GitLab이 모델에 요청할 수 있는지 확인합니다:

model_name = "<your_model_name>"
model_endpoint = "<your_model_endpoint>"
model_api_key = "<your_model_api_key>"
body = {:prompt_components=>[{:type=>"prompt", :metadata=>{:source=>"GitLab EE", :version=>"17.3.0"}, :payload=>{:content=>[{:role=>:user, :content=>"Hello"}], :provider=>:litellm, :model=>model_name, :model_endpoint=>model_endpoint, :model_api_key=>model_api_key}}]}
ai_gateway_url = Ai::Setting.instance.ai_gateway_url # AI Gateway URL이 데이터베이스에 설정되어 있는지 확인
client = Gitlab::Llm::AiGateway::Client.new(User.find_by_id(1), unit_primitive_name: :self_hosted_models)
client.complete(url: "#{ai_gateway_url}/v1/chat/agent", body: body)

다음 형식으로 모델의 응답을 반환해야 합니다:

{"response"=> "",
 "metadata"=>
  {"provider"=>"litellm",
   "model"=>"<>",
   "timestamp"=>1723448920}}

그렇지 않은 경우 다음 중 하나를 의미할 수 있습니다:

사용자가 Code Suggestions에 접근할 수 없을 수 있습니다. 해결하려면 사용자가 Code Suggestions를 요청할 수 있는지 확인합니다.
GitLab 환경 변수가 올바르게 구성되지 않았습니다. 해결하려면 GitLab 환경 변수가 올바르게 설정되어 있는지 확인합니다.
GitLab 인스턴스가 자체 호스팅 모델을 사용하도록 구성되지 않았습니다. 해결하려면 GitLab 인스턴스가 자체 호스팅 모델을 사용하도록 구성되어 있는지 확인합니다.
AI Gateway에 연결할 수 없습니다. 해결하려면 GitLab이 AI Gateway에 HTTP 요청을 할 수 있는지 확인합니다.
LLM 서버가 AI Gateway 컨테이너와 동일한 인스턴스에 설치된 경우 로컬 요청이 작동하지 않을 수 있습니다. 해결하려면 Docker 컨테이너에서 로컬 요청 허용합니다.

사용자가 Code Suggestions를 요청할 수 있는지 확인#

GitLab Rails 콘솔에서 다음을 실행하여 사용자가 Code Suggestions를 요청할 수 있는지 확인합니다:

User.find_by_id("<user_id>").can?(:access_code_suggestions)

이 명령이 false를 반환하면 일부 구성이 누락되어 있고 사용자가 Code Suggestions에 접근할 수 없음을 의미합니다.

이 누락된 구성은 다음 중 하나 때문일 수 있습니다:

라이선스가 유효하지 않습니다. 해결하려면 라이선스를 확인하거나 업데이트합니다.
GitLab Duo가 자체 호스팅 모델을 사용하도록 구성되지 않았습니다. 해결하려면 GitLab 인스턴스가 자체 호스팅 모델을 사용하도록 구성되어 있는지 확인합니다.

GitLab 인스턴스가 자체 호스팅 모델을 사용하도록 구성되어 있는지 확인#

사전 조건:

관리자 권한

GitLab Duo가 올바르게 구성되었는지 확인하려면:

오른쪽 상단에서 관리를 선택합니다.
자체 호스팅 모델을 선택합니다.
AI 네이티브 기능을 확장합니다.
기능 아래에서 Code Suggestions와 코드 생성이 자체 호스팅 모델로 설정되어 있는지 확인합니다.

AI Gateway URL이 올바르게 설정되어 있는지 확인#

AI Gateway URL이 올바른지 확인하려면 GitLab Rails 콘솔에서 다음을 실행합니다:

Ai::Setting.instance.ai_gateway_url == "<your-ai-gateway-instance-url>"

AI Gateway가 설정되지 않은 경우 AI Gateway에 접근하도록 GitLab 인스턴스를 구성합니다.

GitLab Duo Agent Platform 서비스 URL 유효성 검사#

Agent Platform 서비스의 URL이 올바른지 확인하려면 GitLab Rails 콘솔에서 다음을 실행합니다:

Ai::Setting.instance.duo_agent_platform_service_url == "<your-duo-agent-platform-instance-url>"

Agent Platform 서비스의 URL은 TCP URL이며 http:// 또는 https:// 접두사를 가질 수 없습니다.

Agent Platform의 URL이 설정되지 않은 경우 URL에 접근하도록 GitLab 인스턴스를 구성해야 합니다.

GitLab이 AI Gateway에 HTTP 요청을 할 수 있는지 확인#

GitLab Rails 콘솔에서 다음을 실행하여 GitLab이 AI Gateway에 HTTP 요청을 할 수 있는지 확인합니다:

HTTParty.get('<your-aigateway-endpoint>/monitoring/healthz', headers: { 'accept' => 'application/json' }).code

응답이 200이 아닌 경우 다음 중 하나를 의미합니다:

네트워크가 GitLab이 AI Gateway 컨테이너에 도달할 수 있도록 올바르게 구성되지 않았습니다. 네트워크 관리자에게 연락하여 설정을 확인합니다.
AI Gateway가 요청을 처리할 수 없습니다. 이 문제를 해결하려면 AI Gateway가 모델에 요청할 수 있는지 확인합니다.

AI Gateway가 모델에 요청할 수 있는지 확인#

AI Gateway 컨테이너에서 Code Suggestion에 대한 AI Gateway API로 HTTP 요청을 합니다. 다음을 교체합니다:

<your_model_name>을 사용 중인 모델 이름으로 교체합니다. 예: mistral 또는 codegemma
<your_model_endpoint>를 모델이 호스팅된 엔드포인트로 교체합니다.

docker exec -it <ai-gateway-container> sh
curl --request POST "http://localhost:5052/v1/chat/agent" \
     --header 'accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{ "prompt_components": [ { "type": "string", "metadata": { "source": "string", "version": "string" }, "payload": { "content": "Hello", "provider": "litellm", "model": "<your_model_name>", "model_endpoint": "<your_model_endpoint>" } } ], "stream": false }'

요청이 실패하면:

AI Gateway가 자체 호스팅 모델을 사용하도록 올바르게 구성되지 않았을 수 있습니다. 이를 해결하려면 AI Gateway URL이 올바르게 설정되어 있는지 확인합니다.
AI Gateway가 모델에 접근할 수 없을 수 있습니다. 해결하려면 AI Gateway에서 모델에 접근할 수 있는지 확인합니다.
모델 이름 또는 엔드포인트가 잘못되었을 수 있습니다. 값을 확인하고 필요한 경우 수정합니다.

AI Gateway가 요청을 처리할 수 있는지 확인#

docker exec -it <ai-gateway-container> sh
curl '<your-aigateway-endpoint>/monitoring/healthz'

응답이 200이 아닌 경우 AI Gateway가 올바르게 설치되지 않은 것입니다. 해결하려면 AI Gateway 설치 방법에 대한 문서를 따릅니다.

AI Gateway 환경 변수가 올바르게 설정되어 있는지 확인#

AI Gateway 환경 변수가 올바르게 설정되어 있는지 확인하려면 AI Gateway 컨테이너의 콘솔에서 다음을 실행합니다:

docker exec -it <ai-gateway-container> sh
echo $AIGW_CUSTOM_MODELS__ENABLED # must be true

환경 변수가 올바르게 설정되지 않은 경우 컨테이너를 생성하여 설정합니다.

AI Gateway에서 모델에 접근할 수 있는지 확인#

AI Gateway 컨테이너에서 쉘을 만들고 모델에 curl 요청을 합니다. AI Gateway가 해당 요청을 할 수 없는 경우 다음 원인일 수 있습니다:

모델 서버가 올바르게 작동하지 않습니다.
컨테이너 주변의 네트워크 설정이 모델이 호스팅된 위치로의 요청을 허용하도록 올바르게 구성되지 않았습니다.

해결하려면 네트워크 관리자에게 문의합니다.

AI Gateway가 GitLab 인스턴스에 요청을 할 수 있는지 확인#

AIGW_GITLAB_URL에 정의된 GitLab 인스턴스는 요청 인증을 위해 AI Gateway 컨테이너에서 접근 가능해야 합니다. 인스턴스에 접근할 수 없는 경우(예: 프록시 구성 오류로 인해) 요청이 다음과 같은 오류와 함께 실패할 수 있습니다:

jose.exceptions.JWTError: Signature verification failed

gitlab_cloud_connector.providers.CompositeProvider.CriticalAuthError: No keys founds in JWKS; are OIDC providers up?

이 시나리오에서는 AIGW_GITLAB_URL과 $AIGW_GITLAB_API_URL이 컨테이너에 올바르게 설정되고 접근 가능한지 확인합니다. 컨테이너에서 실행할 때 다음 명령이 성공해야 합니다:

poetry run troubleshoot
curl "$AIGW_GITLAB_API_URL/projects"

성공하지 않으면 네트워크 구성을 확인합니다.

이미지 플랫폼이 호스트와 일치하지 않음#

AI Gateway 이미지를 사용할 때, The requested image's platform (linux/amd64) does not match the detected host라는 오류가 발생할 수 있습니다.

이 오류를 해결하려면 docker run 명령에 --platform linux/amd64를 추가합니다:

docker run --platform linux/amd64 -e AIGW_GITLAB_URL=<your-gitlab-endpoint> <image>

LLM 서버가 AI Gateway 컨테이너 내부에서 사용 불가#

LLM 서버가 AI Gateway 컨테이너와 동일한 인스턴스에 설치된 경우 로컬 호스트를 통해 접근하지 못할 수 있습니다.

해결 방법:

docker run 명령에 --network host를 포함하여 AI Gateway 컨테이너에서 로컬 요청을 활성화합니다.
포트 충돌을 해결하기 위해 -e AIGW_FASTAPI__METRICS_PORT=8083 플래그를 사용합니다.

docker run --network host -e AIGW_GITLAB_URL=<your-gitlab-endpoint> -e AIGW_FASTAPI__METRICS_PORT=8083 <image>

vLLM 404 오류#

vLLM을 사용하는 중 404 오류가 발생하면 다음 단계를 따릅니다:

다음 내용으로 chat_template.jinja라는 채팅 템플릿 파일을 만듭니다:

{%- for message in messages %}
  {%- if message["role"] == "user" %}
    {{- "[INST] " + message["content"] + "[/INST]" }}
  {%- elif message["role"] == "assistant" %}
    {{- message["content"] }}
  {%- elif message["role"] == "system" %}
    {{- bos_token }}{{- message["content"] }}
  {%- endif %}
{%- endfor %}

vLLM 명령을 실행할 때 --served-model-name을 지정해야 합니다. 예시:

vllm serve "mistralai/Mistral-7B-Instruct-v0.3" --port <port> --max-model-len 17776 --served-model-name mistral --chat-template chat_template.jinja

GitLab UI에서 vLLM 서버 URL을 확인하여 URL에 /v1 접미사가 포함되어 있는지 확인합니다. 올바른 형식은:
```
http(s)://<your-host>:<your-port>/v1
```

Code Suggestions 접근 오류#

설정 후 Code Suggestions 접근에 문제가 있는 경우 다음 단계를 시도합니다:

Rails 콘솔에서 라이선스 파라미터를 확인하고 검증합니다:

sudo gitlab-rails console
user = User.find(id) # id를 GitLab Duo Enterprise 시트가 제공된 사용자의 ID로 교체
Ability.allowed?(user, :access_code_suggestions) # true를 반환해야 함

필요한 기능이 활성화되어 있고 사용 가능한지 확인합니다:

::Ai::FeatureSetting.exists?(feature: [:code_generations, :code_completions], provider: :self_hosted) # true여야 함

오류 A1000#

자체 호스팅 모델로 GitLab Duo 기능을 사용할 때 다음 오류가 발생할 수 있습니다:

I'm sorry, I couldn't respond in time. Please try again. Error code: A1000

이 문제는 모델에 대한 요청이 구성된 시간 초과 기간보다 오래 걸릴 때 발생합니다.

일반적인 원인:

큰 컨텍스트 창 또는 복잡한 프롬프트
모델 성능 제한
AI Gateway와 모델 엔드포인트 간의 네트워크 지연
교차 지역 추론 지연(AWS Bedrock 배포의 경우)

시간 초과 오류를 해결하려면:

더 높은 AI Gateway 시간 초과 값을 구성합니다. 60초에서 600초(10분) 사이로 시간 초과를 설정할 수 있습니다.
시간 초과를 조정한 후 로그를 모니터링하여 오류가 해결되었는지 확인합니다.
더 높은 시간 초과 값으로도 시간 초과 오류가 지속되는 경우:
- 모델의 성능과 리소스 할당을 확인합니다.
- AI Gateway와 모델 엔드포인트 간의 네트워크 연결을 확인합니다.
- 더 성능이 높은 모델 또는 배포 구성을 사용하는 것을 고려합니다.

GitLab 설정 확인#

GitLab Self-Managed 설정을 확인하려면 다음 명령을 실행합니다:

gitlab-rake gitlab:duo:verify_self_hosted_setup

AI Gateway 서버에서 로그가 생성되지 않음#

AI Gateway 서버에서 로그가 생성되지 않으면 다음 단계에 따라 문제를 해결합니다:

AI 로그가 활성화되어 있는지 확인합니다.
다음 명령을 실행하여 오류에 대한 GitLab Rails 로그를 확인합니다:
```
sudo gitlab-ctl tail
sudo gitlab-ctl tail sidekiq
```
로그에서 근본적인 문제를 식별하기 위해 "Error" 또는 "Exception" 키워드를 찾습니다.

AI Gateway 컨테이너에서 SSL 인증서 오류 및 키 역직렬화 문제#

AI Gateway 컨테이너 내에서 GitLab Duo Chat을 시작하려고 할 때 SSL 인증서 오류와 키 역직렬화 문제가 발생할 수 있습니다.

PEM 파일 로드 문제로 인해 다음과 같은 오류가 발생할 수 있습니다:

JWKError: Could not deserialize key data. The data may be in an incorrect format, the provided password may be incorrect, or it may be encrypted with an unsupported algorithm.

SSL 인증서 오류를 해결하려면:

다음 환경 변수를 사용하여 Docker 컨테이너에서 적절한 인증서 번들 경로를 설정합니다:
- SSL_CERT_FILE=/path/to/ca-bundle.pem
- REQUESTS_CA_BUNDLE=/path/to/ca-bundle.pem

오류: meta 모델 ID 호출이 지원되지 않습니다#

AIGW 로그에서 모델 식별자의 형식이 잘못된 경우 다음 오류가 표시됩니다:

Invocation of model ID meta.llama3-3-70b-instruct-v1:0 with on-demand throughput isn't supported. Retry your request with the ID or ARN of an inference profile that contains this model

model identifier의 형식이 bedrock/<region>.<model-id>인지 확인합니다. 여기서:

<region>은 AWS 지역입니다(예: us)
<model-id>는 전체 모델 식별자입니다.

예시: bedrock/us.meta.llama3-3-70b-instruct-v1:0. 올바른 형식을 사용하도록 모델 구성을 업데이트합니다.

기능에 접근할 수 없거나 기능 버튼이 표시되지 않음#

기능이 작동하지 않거나 기능 버튼(예: /troubleshoot)이 표시되지 않는 경우:

기능의 unit_primitive가 gitlab-cloud-connector 젬 구성의 자체 호스팅 모델 unit primitives 목록에 있는지 확인합니다.

이 파일에 기능이 없으면 접근할 수 없는 이유일 수 있습니다.
선택 사항. 기능이 나열되지 않은 경우 GitLab 인스턴스에서 다음을 설정하여 이것이 문제의 원인인지 확인할 수 있습니다:
```
CLOUD_CONNECTOR_SELF_SIGN_TOKENS=1
```
그런 다음 GitLab을 재시작하고 기능에 접근할 수 있는지 확인합니다.

중요: 문제 해결 후 이 플래그 없이 GitLab을 재시작합니다.

[!warning] 프로덕션에서 CLOUD_CONNECTOR_SELF_SIGN_TOKENS=1을 사용하지 마세요. 개발 환경은 숨겨진 플래그나 내부 전용 해결 방법 없이 프로덕션을 밀접하게 반영해야 합니다.
이 문제를 해결하려면:
- GitLab 팀 멤버인 경우 #g_custom_models Slack 채널을 통해 Custom Models 팀에 문의합니다.
- 고객인 경우 GitLab 지원을 통해 문제를 보고합니다.

오류: 이 워크플로우에 대한 인증 토큰을 가져오는 중 오류가 발생했습니다#

이 오류는 GitLab 또는 로컬 환경에서 에이전트형 Chat을 사용하려고 할 때 발생할 수 있습니다.

IDE의 GitLab Language Server 로그에 다음이 표시될 수 있습니다:

2026-01-09T20:17:43:419 [error]: [WorkflowRailsService] Failed to fetch the workflow token
    Error: Fetching direct_access from https://gitlab.example.com/api/v4/ai/duo_workflows/direct_access failed.
{"message":"400 Bad request - 14:failed to connect to all addresses; last error: UNKNOWN: ipv4:172.x.x.x:50052: Ssl handshake failed (TSI_PROTOCOL_FAILURE): SSL_ERROR_SSL: error:100000f7:SSL routines:OPENSSL_internal:WRONG_VERSION_NUMBER: Invalid certificate verification context. debug_error_string:{UNKNOWN:Error received from peer  {grpc_status:14, grpc_message:\"failed to connect to all addresses; last error: UNKNOWN: ipv4:172.x.x.x:50052: Ssl handshake failed (TSI_PROTOCOL_FAILURE): SSL_ERROR_SSL: error:100000f7:SSL routines:OPENSSL_internal:WRONG_VERSION_NUMBER: Invalid certificate verification context\"}}"}
2026-01-09T20:17:43:433 [error]: Max retries exceeded or non-retryable error: An error occurred while fetching an authentication token for this workflow.
2026-01-09T20:17:43:435 [error]: Workflow failed with status code "50": An error occurred while fetching an authentication token for this workflow.

이는 언어 서버가 인증서 문제로 인해 JWT 토큰을 생성하기 위해 direct_access 엔드포인트와 통신할 수 없었음을 의미합니다.

TLS를 사용하여 자체 호스팅 모델을 Agent Platform에 연결하지 않는 경우 이 문제를 해결하려면 GitLab Duo Agent Platform 서비스에 대한 TLS 연결을 끕니다.

자체 호스팅 모델 문제 해결

Tier: Premium, Ultimate
Offering: GitLab Self-Managed

원문 보기

번역일: 2026-05-22

요약

히스토리

GitLab 17.1에서 ai_custom_model이라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화됩니다.
GitLab 17.6에서 GitLab Self-Managed에서 활성화되었습니다.
GitLab 17.6 이후에 GitLab Duo 애드온이 필요하도록 변경되었습니다.
GitLab 17.8에서 기능 플래그 ai_custom_model이 제거되었습니다.
GitLab 17.9에서 일반 제공됩니다.
GitLab 18.0에서 Premium을 포함하도록 변경되었습니다.

문제 해결을 시작하기 전에 다음을 준비해야 합니다:

gitlab-rails 콘솔에 접근할 수 있어야 합니다.
AI Gateway Docker 이미지에서 쉘을 엽니다.
다음의 엔드포인트를 알고 있어야 합니다:
- AI Gateway가 호스팅된 엔드포인트
- 모델이 호스팅된 엔드포인트
로깅 활성화하여 GitLab에서 AI Gateway로의 요청과 응답이 llm.log에 기록되는지 확인합니다.

GitLab Duo 문제 해결에 대한 자세한 정보는 다음을 참조하세요:

디버깅 스크립트 사용#

관리자가 자체 호스팅 모델 구성을 검증하는 데 도움이 되는 두 가지 디버깅 스크립트를 제공합니다.

GitLab에서 AI Gateway로의 연결을 디버그합니다. GitLab 인스턴스에서 Rake 태스크를 실행합니다:
```
gitlab-rake "gitlab:duo:verify_self_hosted_setup[<username>]"
```
선택 사항: 시트가 할당된 <username>을 포함합니다. 사용자 이름 파라미터를 포함하지 않으면 Rake 태스크는 루트 사용자를 사용합니다.

AI Gateway 설정을 디버그합니다. AI Gateway 컨테이너에서:

인증을 비활성화하여 AI Gateway 컨테이너를 다시 시작합니다:
```
-e AIGW_AUTH__BYPASS_EXTERNAL=true
```
이 설정은 문제 해결 명령이 시스템 교환 테스트를 실행하는 데 필요합니다. 문제 해결이 완료된 후 이 설정을 제거해야 합니다.

AI Gateway 컨테이너에서 다음을 실행합니다:

docker exec -it <ai-gateway-container> sh
poetry run troubleshoot [options]

troubleshoot 명령은 다음 옵션을 지원합니다:

옵션	기본값	예시	설명
`--endpoint`	`localhost:5052`	`--endpoint=localhost:5052`	AI Gateway 엔드포인트
`--model-family`	-	`--model-family=mistral`	테스트할 모델 패밀리. `mistral`, `mixtral`, `gpt`, `claude_3` 중 하나
`--model-endpoint`	-	`--model-endpoint=http://localhost:4000/v1`	모델 엔드포인트. vLLM에서 호스팅된 모델의 경우 `/v1` 접미사를 추가합니다.
`--model-identifier`	-	`--model-identifier=custom_openai/Mixtral-8x7B-Instruct-v0.1`	모델 식별자
`--api-key`	-	`--api-key=your-api-key`	모델 API 키

예시:

AWS Bedrock에서 실행 중인 claude_3 모델:

poetry run troubleshoot \
  --model-family=claude_3 \
  --model-identifier=bedrock/anthropic.claude-3-5-sonnet-20240620-v1:0

vLLM에서 실행 중인 mixtral 모델:

poetry run troubleshoot \
  --model-family=mixtral \
  --model-identifier=custom_openai/Mixtral-8x7B-Instruct-v0.1 \
  --api-key=your-api-key \
  --model-endpoint=http://<your-model-endpoint>/v1

문제 해결이 완료되면 AIGW_AUTH__BYPASS_EXTERNAL=true 없이 AI Gateway 컨테이너를 중지하고 재시작합니다.

Warning

프로덕션에서 인증을 우회해서는 안 됩니다.

명령의 출력을 확인하고 그에 따라 수정합니다.

두 명령이 모두 성공했지만 GitLab Duo Code Suggestions가 여전히 작동하지 않으면 이슈 트래커에 이슈를 제기합니다.

GitLab Duo 상태 확인이 작동하지 않음#

GitLab Duo에 대한 상태 확인을 실행할 때 AI Gateway에서 401 응답과 같은 오류가 발생할 수 있습니다.

해결하려면 먼저 GitLab Duo 기능이 올바르게 작동하는지 확인합니다. 예를 들어 GitLab Duo Chat에 메시지를 보냅니다.

이 방법이 작동하지 않으면 GitLab Duo 상태 확인의 알려진 문제로 인한 오류일 수 있습니다. 자세한 정보는 이슈 517097을 참조하세요.

GitLab이 모델에 요청할 수 있는지 확인#

GitLab Rails 콘솔에서 다음을 실행하여 GitLab이 모델에 요청할 수 있는지 확인합니다:

model_name = "<your_model_name>"
model_endpoint = "<your_model_endpoint>"
model_api_key = "<your_model_api_key>"
body = {:prompt_components=>[{:type=>"prompt", :metadata=>{:source=>"GitLab EE", :version=>"17.3.0"}, :payload=>{:content=>[{:role=>:user, :content=>"Hello"}], :provider=>:litellm, :model=>model_name, :model_endpoint=>model_endpoint, :model_api_key=>model_api_key}}]}
ai_gateway_url = Ai::Setting.instance.ai_gateway_url # AI Gateway URL이 데이터베이스에 설정되어 있는지 확인
client = Gitlab::Llm::AiGateway::Client.new(User.find_by_id(1), unit_primitive_name: :self_hosted_models)
client.complete(url: "#{ai_gateway_url}/v1/chat/agent", body: body)

다음 형식으로 모델의 응답을 반환해야 합니다:

{"response"=> "",
 "metadata"=>
  {"provider"=>"litellm",
   "model"=>"<>",
   "timestamp"=>1723448920}}

그렇지 않은 경우 다음 중 하나를 의미할 수 있습니다:

사용자가 Code Suggestions에 접근할 수 없을 수 있습니다. 해결하려면 사용자가 Code Suggestions를 요청할 수 있는지 확인합니다.
GitLab 환경 변수가 올바르게 구성되지 않았습니다. 해결하려면 GitLab 환경 변수가 올바르게 설정되어 있는지 확인합니다.
GitLab 인스턴스가 자체 호스팅 모델을 사용하도록 구성되지 않았습니다. 해결하려면 GitLab 인스턴스가 자체 호스팅 모델을 사용하도록 구성되어 있는지 확인합니다.
AI Gateway에 연결할 수 없습니다. 해결하려면 GitLab이 AI Gateway에 HTTP 요청을 할 수 있는지 확인합니다.
LLM 서버가 AI Gateway 컨테이너와 동일한 인스턴스에 설치된 경우 로컬 요청이 작동하지 않을 수 있습니다. 해결하려면 Docker 컨테이너에서 로컬 요청 허용합니다.

사용자가 Code Suggestions를 요청할 수 있는지 확인#

GitLab Rails 콘솔에서 다음을 실행하여 사용자가 Code Suggestions를 요청할 수 있는지 확인합니다:

User.find_by_id("<user_id>").can?(:access_code_suggestions)

이 명령이 false를 반환하면 일부 구성이 누락되어 있고 사용자가 Code Suggestions에 접근할 수 없음을 의미합니다.

이 누락된 구성은 다음 중 하나 때문일 수 있습니다:

라이선스가 유효하지 않습니다. 해결하려면 라이선스를 확인하거나 업데이트합니다.
GitLab Duo가 자체 호스팅 모델을 사용하도록 구성되지 않았습니다. 해결하려면 GitLab 인스턴스가 자체 호스팅 모델을 사용하도록 구성되어 있는지 확인합니다.

GitLab 인스턴스가 자체 호스팅 모델을 사용하도록 구성되어 있는지 확인#

사전 조건:

관리자 권한

GitLab Duo가 올바르게 구성되었는지 확인하려면:

오른쪽 상단에서 관리를 선택합니다.
자체 호스팅 모델을 선택합니다.
AI 네이티브 기능을 확장합니다.
기능 아래에서 Code Suggestions와 코드 생성이 자체 호스팅 모델로 설정되어 있는지 확인합니다.

AI Gateway URL이 올바르게 설정되어 있는지 확인#

AI Gateway URL이 올바른지 확인하려면 GitLab Rails 콘솔에서 다음을 실행합니다:

Ai::Setting.instance.ai_gateway_url == "<your-ai-gateway-instance-url>"

AI Gateway가 설정되지 않은 경우 AI Gateway에 접근하도록 GitLab 인스턴스를 구성합니다.

GitLab Duo Agent Platform 서비스 URL 유효성 검사#

Agent Platform 서비스의 URL이 올바른지 확인하려면 GitLab Rails 콘솔에서 다음을 실행합니다:

Ai::Setting.instance.duo_agent_platform_service_url == "<your-duo-agent-platform-instance-url>"

Agent Platform 서비스의 URL은 TCP URL이며 http:// 또는 https:// 접두사를 가질 수 없습니다.

Agent Platform의 URL이 설정되지 않은 경우 URL에 접근하도록 GitLab 인스턴스를 구성해야 합니다.

GitLab이 AI Gateway에 HTTP 요청을 할 수 있는지 확인#

GitLab Rails 콘솔에서 다음을 실행하여 GitLab이 AI Gateway에 HTTP 요청을 할 수 있는지 확인합니다:

HTTParty.get('<your-aigateway-endpoint>/monitoring/healthz', headers: { 'accept' => 'application/json' }).code

응답이 200이 아닌 경우 다음 중 하나를 의미합니다:

네트워크가 GitLab이 AI Gateway 컨테이너에 도달할 수 있도록 올바르게 구성되지 않았습니다. 네트워크 관리자에게 연락하여 설정을 확인합니다.
AI Gateway가 요청을 처리할 수 없습니다. 이 문제를 해결하려면 AI Gateway가 모델에 요청할 수 있는지 확인합니다.

AI Gateway가 모델에 요청할 수 있는지 확인#

AI Gateway 컨테이너에서 Code Suggestion에 대한 AI Gateway API로 HTTP 요청을 합니다. 다음을 교체합니다:

<your_model_name>을 사용 중인 모델 이름으로 교체합니다. 예: mistral 또는 codegemma
<your_model_endpoint>를 모델이 호스팅된 엔드포인트로 교체합니다.

docker exec -it <ai-gateway-container> sh
curl --request POST "http://localhost:5052/v1/chat/agent" \
     --header 'accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{ "prompt_components": [ { "type": "string", "metadata": { "source": "string", "version": "string" }, "payload": { "content": "Hello", "provider": "litellm", "model": "<your_model_name>", "model_endpoint": "<your_model_endpoint>" } } ], "stream": false }'

요청이 실패하면:

AI Gateway가 자체 호스팅 모델을 사용하도록 올바르게 구성되지 않았을 수 있습니다. 이를 해결하려면 AI Gateway URL이 올바르게 설정되어 있는지 확인합니다.
AI Gateway가 모델에 접근할 수 없을 수 있습니다. 해결하려면 AI Gateway에서 모델에 접근할 수 있는지 확인합니다.
모델 이름 또는 엔드포인트가 잘못되었을 수 있습니다. 값을 확인하고 필요한 경우 수정합니다.

AI Gateway가 요청을 처리할 수 있는지 확인#

docker exec -it <ai-gateway-container> sh
curl '<your-aigateway-endpoint>/monitoring/healthz'

응답이 200이 아닌 경우 AI Gateway가 올바르게 설치되지 않은 것입니다. 해결하려면 AI Gateway 설치 방법에 대한 문서를 따릅니다.

AI Gateway 환경 변수가 올바르게 설정되어 있는지 확인#

AI Gateway 환경 변수가 올바르게 설정되어 있는지 확인하려면 AI Gateway 컨테이너의 콘솔에서 다음을 실행합니다:

docker exec -it <ai-gateway-container> sh
echo $AIGW_CUSTOM_MODELS__ENABLED # must be true

환경 변수가 올바르게 설정되지 않은 경우 컨테이너를 생성하여 설정합니다.

AI Gateway에서 모델에 접근할 수 있는지 확인#

AI Gateway 컨테이너에서 쉘을 만들고 모델에 curl 요청을 합니다. AI Gateway가 해당 요청을 할 수 없는 경우 다음 원인일 수 있습니다:

모델 서버가 올바르게 작동하지 않습니다.
컨테이너 주변의 네트워크 설정이 모델이 호스팅된 위치로의 요청을 허용하도록 올바르게 구성되지 않았습니다.

해결하려면 네트워크 관리자에게 문의합니다.

AI Gateway가 GitLab 인스턴스에 요청을 할 수 있는지 확인#

jose.exceptions.JWTError: Signature verification failed

gitlab_cloud_connector.providers.CompositeProvider.CriticalAuthError: No keys founds in JWKS; are OIDC providers up?

poetry run troubleshoot
curl "$AIGW_GITLAB_API_URL/projects"

성공하지 않으면 네트워크 구성을 확인합니다.

이미지 플랫폼이 호스트와 일치하지 않음#

AI Gateway 이미지를 사용할 때, The requested image's platform (linux/amd64) does not match the detected host라는 오류가 발생할 수 있습니다.

이 오류를 해결하려면 docker run 명령에 --platform linux/amd64를 추가합니다:

docker run --platform linux/amd64 -e AIGW_GITLAB_URL=<your-gitlab-endpoint> <image>

LLM 서버가 AI Gateway 컨테이너 내부에서 사용 불가#

LLM 서버가 AI Gateway 컨테이너와 동일한 인스턴스에 설치된 경우 로컬 호스트를 통해 접근하지 못할 수 있습니다.

해결 방법:

docker run 명령에 --network host를 포함하여 AI Gateway 컨테이너에서 로컬 요청을 활성화합니다.
포트 충돌을 해결하기 위해 -e AIGW_FASTAPI__METRICS_PORT=8083 플래그를 사용합니다.

docker run --network host -e AIGW_GITLAB_URL=<your-gitlab-endpoint> -e AIGW_FASTAPI__METRICS_PORT=8083 <image>

vLLM 404 오류#

vLLM을 사용하는 중 404 오류가 발생하면 다음 단계를 따릅니다:

다음 내용으로 chat_template.jinja라는 채팅 템플릿 파일을 만듭니다:

{%- for message in messages %}
  {%- if message["role"] == "user" %}
    {{- "[INST] " + message["content"] + "[/INST]" }}
  {%- elif message["role"] == "assistant" %}
    {{- message["content"] }}
  {%- elif message["role"] == "system" %}
    {{- bos_token }}{{- message["content"] }}
  {%- endif %}
{%- endfor %}

vLLM 명령을 실행할 때 --served-model-name을 지정해야 합니다. 예시:

vllm serve "mistralai/Mistral-7B-Instruct-v0.3" --port <port> --max-model-len 17776 --served-model-name mistral --chat-template chat_template.jinja

GitLab UI에서 vLLM 서버 URL을 확인하여 URL에 /v1 접미사가 포함되어 있는지 확인합니다. 올바른 형식은:
```
http(s)://<your-host>:<your-port>/v1
```

Code Suggestions 접근 오류#

설정 후 Code Suggestions 접근에 문제가 있는 경우 다음 단계를 시도합니다:

Rails 콘솔에서 라이선스 파라미터를 확인하고 검증합니다:

sudo gitlab-rails console
user = User.find(id) # id를 GitLab Duo Enterprise 시트가 제공된 사용자의 ID로 교체
Ability.allowed?(user, :access_code_suggestions) # true를 반환해야 함

필요한 기능이 활성화되어 있고 사용 가능한지 확인합니다:

::Ai::FeatureSetting.exists?(feature: [:code_generations, :code_completions], provider: :self_hosted) # true여야 함

오류 A1000#

자체 호스팅 모델로 GitLab Duo 기능을 사용할 때 다음 오류가 발생할 수 있습니다:

I'm sorry, I couldn't respond in time. Please try again. Error code: A1000

이 문제는 모델에 대한 요청이 구성된 시간 초과 기간보다 오래 걸릴 때 발생합니다.

일반적인 원인:

큰 컨텍스트 창 또는 복잡한 프롬프트
모델 성능 제한
AI Gateway와 모델 엔드포인트 간의 네트워크 지연
교차 지역 추론 지연(AWS Bedrock 배포의 경우)

시간 초과 오류를 해결하려면:

더 높은 AI Gateway 시간 초과 값을 구성합니다. 60초에서 600초(10분) 사이로 시간 초과를 설정할 수 있습니다.
시간 초과를 조정한 후 로그를 모니터링하여 오류가 해결되었는지 확인합니다.
더 높은 시간 초과 값으로도 시간 초과 오류가 지속되는 경우:
- 모델의 성능과 리소스 할당을 확인합니다.
- AI Gateway와 모델 엔드포인트 간의 네트워크 연결을 확인합니다.
- 더 성능이 높은 모델 또는 배포 구성을 사용하는 것을 고려합니다.

GitLab 설정 확인#

GitLab Self-Managed 설정을 확인하려면 다음 명령을 실행합니다:

gitlab-rake gitlab:duo:verify_self_hosted_setup

AI Gateway 서버에서 로그가 생성되지 않음#

AI Gateway 서버에서 로그가 생성되지 않으면 다음 단계에 따라 문제를 해결합니다:

AI 로그가 활성화되어 있는지 확인합니다.
다음 명령을 실행하여 오류에 대한 GitLab Rails 로그를 확인합니다:
```
sudo gitlab-ctl tail
sudo gitlab-ctl tail sidekiq
```
로그에서 근본적인 문제를 식별하기 위해 "Error" 또는 "Exception" 키워드를 찾습니다.

AI Gateway 컨테이너에서 SSL 인증서 오류 및 키 역직렬화 문제#

AI Gateway 컨테이너 내에서 GitLab Duo Chat을 시작하려고 할 때 SSL 인증서 오류와 키 역직렬화 문제가 발생할 수 있습니다.

PEM 파일 로드 문제로 인해 다음과 같은 오류가 발생할 수 있습니다:

JWKError: Could not deserialize key data. The data may be in an incorrect format, the provided password may be incorrect, or it may be encrypted with an unsupported algorithm.

SSL 인증서 오류를 해결하려면:

다음 환경 변수를 사용하여 Docker 컨테이너에서 적절한 인증서 번들 경로를 설정합니다:
- SSL_CERT_FILE=/path/to/ca-bundle.pem
- REQUESTS_CA_BUNDLE=/path/to/ca-bundle.pem

오류: meta 모델 ID 호출이 지원되지 않습니다#

AIGW 로그에서 모델 식별자의 형식이 잘못된 경우 다음 오류가 표시됩니다:

Invocation of model ID meta.llama3-3-70b-instruct-v1:0 with on-demand throughput isn't supported. Retry your request with the ID or ARN of an inference profile that contains this model

model identifier의 형식이 bedrock/<region>.<model-id>인지 확인합니다. 여기서:

<region>은 AWS 지역입니다(예: us)
<model-id>는 전체 모델 식별자입니다.

예시: bedrock/us.meta.llama3-3-70b-instruct-v1:0. 올바른 형식을 사용하도록 모델 구성을 업데이트합니다.

기능에 접근할 수 없거나 기능 버튼이 표시되지 않음#

기능이 작동하지 않거나 기능 버튼(예: /troubleshoot)이 표시되지 않는 경우:

기능의 unit_primitive가 gitlab-cloud-connector 젬 구성의 자체 호스팅 모델 unit primitives 목록에 있는지 확인합니다.

이 파일에 기능이 없으면 접근할 수 없는 이유일 수 있습니다.
선택 사항. 기능이 나열되지 않은 경우 GitLab 인스턴스에서 다음을 설정하여 이것이 문제의 원인인지 확인할 수 있습니다:
```
CLOUD_CONNECTOR_SELF_SIGN_TOKENS=1
```
그런 다음 GitLab을 재시작하고 기능에 접근할 수 있는지 확인합니다.

중요: 문제 해결 후 이 플래그 없이 GitLab을 재시작합니다.

[!warning] 프로덕션에서 CLOUD_CONNECTOR_SELF_SIGN_TOKENS=1을 사용하지 마세요. 개발 환경은 숨겨진 플래그나 내부 전용 해결 방법 없이 프로덕션을 밀접하게 반영해야 합니다.
이 문제를 해결하려면:
- GitLab 팀 멤버인 경우 #g_custom_models Slack 채널을 통해 Custom Models 팀에 문의합니다.
- 고객인 경우 GitLab 지원을 통해 문제를 보고합니다.

오류: 이 워크플로우에 대한 인증 토큰을 가져오는 중 오류가 발생했습니다#

이 오류는 GitLab 또는 로컬 환경에서 에이전트형 Chat을 사용하려고 할 때 발생할 수 있습니다.

IDE의 GitLab Language Server 로그에 다음이 표시될 수 있습니다:

2026-01-09T20:17:43:419 [error]: [WorkflowRailsService] Failed to fetch the workflow token
    Error: Fetching direct_access from https://gitlab.example.com/api/v4/ai/duo_workflows/direct_access failed.
{"message":"400 Bad request - 14:failed to connect to all addresses; last error: UNKNOWN: ipv4:172.x.x.x:50052: Ssl handshake failed (TSI_PROTOCOL_FAILURE): SSL_ERROR_SSL: error:100000f7:SSL routines:OPENSSL_internal:WRONG_VERSION_NUMBER: Invalid certificate verification context. debug_error_string:{UNKNOWN:Error received from peer  {grpc_status:14, grpc_message:\"failed to connect to all addresses; last error: UNKNOWN: ipv4:172.x.x.x:50052: Ssl handshake failed (TSI_PROTOCOL_FAILURE): SSL_ERROR_SSL: error:100000f7:SSL routines:OPENSSL_internal:WRONG_VERSION_NUMBER: Invalid certificate verification context\"}}"}
2026-01-09T20:17:43:433 [error]: Max retries exceeded or non-retryable error: An error occurred while fetching an authentication token for this workflow.
2026-01-09T20:17:43:435 [error]: Workflow failed with status code "50": An error occurred while fetching an authentication token for this workflow.

이는 언어 서버가 인증서 문제로 인해 JWT 토큰을 생성하기 위해 direct_access 엔드포인트와 통신할 수 없었음을 의미합니다.

TLS를 사용하여 자체 호스팅 모델을 Agent Platform에 연결하지 않는 경우 이 문제를 해결하려면 GitLab Duo Agent Platform 서비스에 대한 TLS 연결을 끕니다.

자체 호스팅 모델 문제 해결

디버깅 스크립트 사용#

GitLab Duo 상태 확인이 작동하지 않음#

GitLab이 모델에 요청할 수 있는지 확인#

사용자가 Code Suggestions를 요청할 수 있는지 확인#

GitLab 인스턴스가 자체 호스팅 모델을 사용하도록 구성되어 있는지 확인#

AI Gateway URL이 올바르게 설정되어 있는지 확인#

GitLab Duo Agent Platform 서비스 URL 유효성 검사#

GitLab이 AI Gateway에 HTTP 요청을 할 수 있는지 확인#

AI Gateway가 모델에 요청할 수 있는지 확인#

AI Gateway가 요청을 처리할 수 있는지 확인#

AI Gateway 환경 변수가 올바르게 설정되어 있는지 확인#

AI Gateway에서 모델에 접근할 수 있는지 확인#

AI Gateway가 GitLab 인스턴스에 요청을 할 수 있는지 확인#

이미지 플랫폼이 호스트와 일치하지 않음#

LLM 서버가 AI Gateway 컨테이너 내부에서 사용 불가#

vLLM 404 오류#

Code Suggestions 접근 오류#

오류 A1000#

GitLab 설정 확인#

AI Gateway 서버에서 로그가 생성되지 않음#

AI Gateway 컨테이너에서 SSL 인증서 오류 및 키 역직렬화 문제#

오류: meta 모델 ID 호출이 지원되지 않습니다#

기능에 접근할 수 없거나 기능 버튼이 표시되지 않음#

오류: 이 워크플로우에 대한 인증 토큰을 가져오는 중 오류가 발생했습니다#

관련 항목#

디버깅 스크립트 사용#

GitLab Duo 상태 확인이 작동하지 않음#

GitLab이 모델에 요청할 수 있는지 확인#

사용자가 Code Suggestions를 요청할 수 있는지 확인#

GitLab 인스턴스가 자체 호스팅 모델을 사용하도록 구성되어 있는지 확인#

AI Gateway URL이 올바르게 설정되어 있는지 확인#

GitLab Duo Agent Platform 서비스 URL 유효성 검사#

GitLab이 AI Gateway에 HTTP 요청을 할 수 있는지 확인#

AI Gateway가 모델에 요청할 수 있는지 확인#

AI Gateway가 요청을 처리할 수 있는지 확인#

AI Gateway 환경 변수가 올바르게 설정되어 있는지 확인#

AI Gateway에서 모델에 접근할 수 있는지 확인#

AI Gateway가 GitLab 인스턴스에 요청을 할 수 있는지 확인#

이미지 플랫폼이 호스트와 일치하지 않음#

LLM 서버가 AI Gateway 컨테이너 내부에서 사용 불가#

vLLM 404 오류#

Code Suggestions 접근 오류#

오류 A1000#

GitLab 설정 확인#

AI Gateway 서버에서 로그가 생성되지 않음#

AI Gateway 컨테이너에서 SSL 인증서 오류 및 키 역직렬화 문제#

오류: meta 모델 ID 호출이 지원되지 않습니다#

기능에 접근할 수 없거나 기능 버튼이 표시되지 않음#

오류: 이 워크플로우에 대한 인증 토큰을 가져오는 중 오류가 발생했습니다#

관련 항목#