GitLab Duo Self-Hosted 모델의 문제 해결

GitLab Duo Self-Hosted 모델을 사용할 때 문제가 발생할 수 있습니다.

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

  • gitlab-rails 콘솔에 액세스할 수 있어야 합니다.
  • AI Gateway Docker 이미지에서 셸을 열 수 있어야 합니다.
  • 다음의 엔드포인트를 알고 있어야 합니다:
    • AI Gateway가 호스팅된 위치.
    • 모델이 호스팅된 위치.

  • gitlab-rails 콘솔에서 기능 플래그 expanded_ai_logging을 활성화해야 합니다: 

    Feature.enable(:expanded_ai_logging)

    이제 GitLab에서 AI Gateway로의 요청과 응답이 llm.log에 로그됩니다.

디버깅 스크립트 사용

관리자가 자체 호스팅 모델 구성을 확인하는 데 도움을 줄 수 있는 디버깅 스크립트를 제공합니다.

  1. GitLab에서 AI Gateway 연결을 디버그합니다. GitLab 인스턴스에서 다음 Rake 작업을 실행하세요: 

    gitlab-rake gitlab:duo:verify_self_hosted_setup

  2. AI Gateway 설정을 디버깅합니다. AI Gateway 컨테이너에서 다음을 실행하세요: 

    docker exec -it <ai-gateway-container> sh
poetry run python scripts/troubleshoot_selfhosted_installation.py --model-name "codegemma_7b" --model-endpoint
"http://localhost:4000"

위 명령어의 출력을 확인하고 이에 따라 수정하세요.

만약 두 명령어 모두 성공했지만 GitLab Duo Code Suggestions가 여전히 작동하지 않는다면, 이슈 트래커에 이슈를 등록하세요.

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 = Gitlab::AiGateway.url # nil이 아닌지 확인
client = Gitlab::Llm::AiGateway::Client.new(User.find_by_id(1), service_name: :self_hosted_models)
client.complete(url: "#{ai_gateway_url}/v1/chat/agent", body: body)

이 명령어는 모델에서 형식에 맞는 응답을 반환해야 합니다: 

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

그렇지 않다면, 다음 중 하나의 이유일 수 있습니다:

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

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

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

이 명령어가 false를 반환하면 구성이 누락되어 사용자가 Code Suggestions에 액세스할 수 없는 것입니다.

이 구성이 누락된 이유는 다음 중 하나일 수 있습니다:

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

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

  1. 왼쪽 사이드바에서 맨 아래 관리자를 선택합니다.
  2. 설정 > 일반을 선택합니다.
  3. AI 기능을 확장합니다.
  4. 기능 아래에서 Code Suggestions 및 Code generation이 Self-hosted model로 설정되었는지 확인합니다.

GitLab 환경 변수가 올바르게 설정되었는지 확인

GitLab 환경 변수가 올바르게 설정되었는지 확인하려면 GitLab Rails 콘솔에서 다음을 실행하세요: 

ENV["AI_GATEWAY_URL"] == "<your-ai-gateway-endpoint>"

환경 변수가 올바르게 설정되지 않았다면, Linux 패키지 사용자 정의 환경 변수 설정 문서에 따라 설정하세요.

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 게이트웨이가 모델에 요청을 보낼 수 있는지 확인

AI 게이트웨이 컨테이너에서 AI 게이트웨이 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 게이트웨이가 요청을 처리할 수 있는지 확인 

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

응답이 200이 아니라면, 이는 AI 게이트웨이가 올바르게 설치되지 않았음을 나타냅니다. 해결하려면 AI 게이트웨이를 설치하는 방법에 대한 문서를 참조하십시오.

AI 게이트웨이 환경 변수가 올바르게 설정되었는지 확인하십시오

AI 게이트웨이 환경 변수가 올바르게 설정되었는지 확인하려면 AI 게이트웨이 컨테이너에서 콘솔에서 다음을 실행하십시오: 

docker exec -it <ai-gateway-container> sh
echo $AIGW_AUTH__BYPASS_EXTERNAL # true 여야 함
echo $AIGW_CUSTOM_MODELS__ENABLED # true 여야 함

환경 변수가 올바르게 설정되지 않았다면, 컨테이너를 만들어서 설정하십시오.

AI 게이트웨이에서 모델에 액세스할 수 있는지 확인하십시오

AI 게이트웨이 컨테이너에서 쉘을 만들고 모델에 대한 curl 요청을 보내십시오. AI 게이트웨이가 해당 요청을 할 수 없다면, 이는 다음으로 인해 발생할 수 있습니다:

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

이를 해결하려면 네트워크 관리자에게 문의하십시오.

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

AI 게이트웨이 릴리스를 찾을 때, 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>

AI 게이트웨이 컨테이너 내 LLM 서버를 사용할 수 없음

만약 LLM 서버가 AI 게이트웨이 컨테이너와 동일한 인스턴스에 설치된 경우, 로컬 호스트를 통해 액세스할 수 없을 수 있습니다.

이를 해결하려면:

  1. docker run 명령에 --network host를 포함하여 AI 게이트웨이 컨테이너에서 로컬 요청을 활성화하십시오.
  2. -e AIGW_FASTAPI__METRICS_PORT=8083 플래그를 사용하여 포트 충돌을 해결하십시오. 
docker run --network host -e AIGW_GITLAB_URL=<your-gitlab-endpoint> -e AIGW_FASTAPI__METRICS_PORT=8083 <image>