Help us learn about your current experience with the documentation. Take the survey.

GitLab Duo 自托管版故障排除

Tier: Premium, Ultimate
Add-on: GitLab Duo Enterprise
Offering: GitLab Self-Managed

在使用 GitLab Duo 自托管版时，您可能会遇到一些问题。

在开始故障排除之前，您应该：

能够访问 gitlab-rails 控制台。
在 AI 网关 Docker 镜像中打开一个 shell。
了解您的以下托管端点：
- AI 网关
- 模型
启用日志记录，以确保从 GitLab 到 AI 网关的请求和响应都被记录到 llm.log 中。

有关 GitLab Duo 故障排除的更多信息，请参阅：

使用调试脚本

我们提供了两个调试脚本来帮助管理员验证其自托管模型配置。

调试 GitLab 到 AI 网关的连接。在您的 GitLab 实例上，运行 Rake 任务：
```
gitlab-rake "gitlab:duo:verify_self_hosted_setup[<username>]"
```
可选：包含一个已分配席位的 <username>。如果您不包含用户名参数，Rake 任务将使用 root 用户。

调试 AI 网关设置。对于您的 AI 网关容器：

通过设置以下内容，在禁用身份验证的情况下重启 AI 网关容器：
```
-e AIGW_AUTH__BYPASS_EXTERNAL=true
```
此设置是运行系统交换测试的故障排除命令所必需的。故障排除完成后，您必须移除此设置。

在您的 AI 网关容器中，运行：

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

troubleshoot 命令支持以下选项：

选项	默认值	示例	描述
`--endpoint`	`localhost:5052`	`--endpoint=localhost:5052`	AI 网关端点
`--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

故障排除完成后，请停止并重启 AI 网关容器，不要使用 AIGW_AUTH__BYPASS_EXTERNAL=true。

您不得在生产环境中绕过身份验证。

验证命令的输出，并相应地进行修复。

如果两个命令都成功，但 GitLab Duo 代码建议仍然不工作，请在问题跟踪器上提交一个问题。

GitLab Duo 健康检查不工作

当您为 GitLab Duo 运行健康检查时，可能会收到类似 来自 AI 网关的 401 响应 的错误。

要解决此问题，首先检查 GitLab Duo 功能是否正常工作。例如，向 Duo 聊天发送一条消息。

如果这不起作用，则该错误可能是由于 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 网关 URL 是否已在数据库中设置
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}}

如果不是这种情况，则可能意味着以下原因之一：

用户可能无权访问代码建议。要解决此问题，检查用户是否可以请求代码建议。
GitLab 环境变量未正确配置。要解决此问题，检查 GitLab 环境变量是否已正确设置。
GitLab 实例未配置为使用自托管模型。要解决此问题，检查 GitLab 实例是否已配置为使用自托管模型。
AI 网关无法访问。要解决此问题，检查 GitLab 是否可以向 AI 网关发送 HTTP 请求。
当 LLM 服务器与 AI 网关容器安装在同一实例上时，本地请求可能无法工作。要解决此问题，允许来自 Docker 容器的本地请求。

检查用户是否可以请求代码建议

在 GitLab Rails 控制台中，通过运行以下命令来检查用户是否可以请求代码建议：

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

如果返回 false，则表示缺少某些配置，并且该用户无法访问代码建议。

这种缺少的配置可能是由于以下原因之一：

许可证无效。要解决此问题，检查或更新您的许可证。
GitLab Duo 未配置为使用自托管模型。要解决此问题，检查 GitLab 实例是否已配置为使用自托管模型。

检查 GitLab 实例是否已配置为使用自托管模型

要检查 GitLab Duo 是否已正确配置：

在左侧边栏的底部，选择 管理员。
选择 自托管模型
展开 AI 原生功能。
在功能下，检查 代码建议 和 代码生成 是否设置为 自托管模型。

检查 AI 网关 URL 是否已正确设置

要检查 AI 网关 URL 是否正确，请在 GitLab Rails 控制台上运行以下命令：

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

如果 AI 网关未设置，请配置您的 GitLab 实例以访问 AI 网关。

检查 GitLab 是否可以向 AI 网关发送 HTTP 请求

在 GitLab Rails 控制台中，通过运行以下命令来验证 GitLab 是否可以向 AI 网关发送 HTTP 请求：

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

如果响应不是 200，则表示以下情况之一：

网络未正确配置以允许 GitLab 访问 AI 网关容器。请联系您的网络管理员以验证设置。
AI 网关无法处理请求。要解决此问题，检查 AI 网关是否可以向模型发送请求。

检查 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 网关未正确配置为使用自托管模型。要解决此问题，检查 AI 网关 URL 是否已正确设置。
AI 网关可能无法访问模型。要解决此问题，检查模型是否可以从 AI 网关访问。
模型名称或端点可能不正确。请检查这些值，并在必要时进行更正。

检查 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_CUSTOM_MODELS__ENABLED # 必须为 true

如果环境变量未正确设置，请通过创建容器来设置它们。

检查模型是否可以从 AI 网关访问

在 AI 网关容器上创建一个 shell，并向模型发出一个 curl 请求。如果您发现 AI 网关无法发出该请求，这可能是由以下原因引起的：

模型服务器运行不正常。
容器周围的网络设置未正确配置以允许向模型托管位置发送请求。

要解决此问题，请联系您的网络管理员。

检查 AI 网关是否可以向您的 GitLab 实例发送请求

在 AIGW_GITLAB_URL 中定义的 GitLab 实例必须可从 AI 网关容器访问，以便进行请求身份验证。如果实例无法访问（例如，由于代理配置错误），请求可能会失败，并出现如下错误：

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 网关版本时，您可能会收到一条错误消息，指出 所请求镜像的平台 (linux/amd64) 与检测到的主机不匹配。

要解决此错误，请在 docker run 命令中添加 --platform linux/amd64：

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

LLM 服务器在 AI 网关容器内不可用

如果 LLM 服务器与 AI 网关容器安装在同一实例上，则可能无法通过本地主机访问它。

要解决此问题：

在 docker run 命令中包含 --network host，以允许来自 AI 网关容器的本地请求。
使用 -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
```

代码建议访问错误

如果您在设置后遇到访问代码建议的问题，请尝试以下步骤：

在 Rails 控制台中，检查并验证许可证参数：

sudo gitlab-rails console
user = User.find(id) # 将 id 替换为已分配 GitLab Duo Enterprise 席位的用户
Ability.allowed?(user, :access_code_suggestions) # 必须返回 true

检查必要的功能是否已启用并可用：

::Ai::FeatureSetting.code_suggestions_self_hosted? # 应该为 true

验证 GitLab 设置

要验证您的 GitLab 自管理版设置，请运行以下命令：

gitlab-rake gitlab:duo:verify_self_hosted_setup

AI 网关服务器中未生成日志

如果在 AI 网关服务器中没有生成日志，请按照以下步骤进行故障排除：

确保AI 日志已启用。
运行以下命令以查看 GitLab Rails 日志中的任何错误：
```
sudo gitlab-ctl tail
sudo gitlab-ctl tail sidekiq
```
在日志中查找“Error”或“Exception”等关键词，以识别任何潜在问题。

AI 网关容器中的 SSL 证书错误和密钥反序列化问题

尝试在 AI 网关容器内启动 Duo 聊天时，可能会发生 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

Duo 聊天常见错误故障排除

错误 A1000

您可能会收到一条错误消息，指出 抱歉，我无法及时响应。请重试。错误代码：A1000。

此错误在处理过程中发生超时时出现。请重试您的请求。

错误 A1001

您可能会收到一条错误消息，指出 抱歉，我无法生成响应。请重试。错误代码：A1001。

此错误表示连接到 AI 网关时出现问题。您可能需要检查网络设置，并确保 AI 网关可从 GitLab 实例访问。

使用自托管调试脚本来验证 AI 网关是否可从 GitLab 实例访问并按预期工作。

如果问题仍然存在，请将问题报告给 GitLab 支持团队。

错误 A1002

您可能会收到一条错误消息，指出 抱歉，我无法及时响应。请重试。错误代码：A1002。

此错误在 AI 网关未返回任何事件或 GitLab 无法解析事件时发生。请检查 AI 网关日志中是否有任何错误。

错误 A1003

您可能会收到一条错误消息，指出 抱歉，我无法及时响应。请重试。错误代码：A1003。

此错误通常是由于从模型到 AI 网关的流式传输出现问题。要解决此问题：

在 AI 网关容器中，运行以下命令：

curl --request 'POST' \
'http://localhost:5052/v2/chat/agent' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-gitlab-enabled-instance-verbose-ai-logs: true' \
--data '{
  "messages": [
    {
      "role": "user",
      "content": "Hello",
      "context": null,
      "current_file": null,
      "additional_context": []
    }
  ],
  "model_metadata": {
    "provider": "custom_openai",
    "name": "mistral",
    "endpoint": "<change here>",
    "api_key": "<change here>",
    "identifier": "<change here>"
  },
  "unavailable_resources": [],
  "options": {
    "agent_scratchpad": {
      "agent_type": "react",
      "steps": []
    }
  }
}'

如果流式传输正常工作，应该会显示分块响应。如果不是，则可能会显示空响应。

检查 AI 网关日志中是否有特定的错误消息，因为这通常是模型部署问题。
要验证连接，请在您的 AI 网关容器中设置 AIGW_CUSTOM_MODELS__DISABLE_STREAMING 环境变量以禁用流式传输：
```
docker run .... -e AIGW_CUSTOM_MODELS__DISABLE_STREAMING=true ...
```

错误 A9999

您可能会收到一条错误消息，指出 抱歉，我无法生成响应。请重试。错误代码：A9999。

此错误在 ReAct 代理中发生未知错误时出现。请重试您的请求。如果问题仍然存在，请将问题报告给 GitLab 支持团队。

功能不可访问或功能按钮不可见

如果某个功能不工作或功能按钮（例如，/troubleshoot）不可见：

检查该功能的 unit_primitive 是否列在 gitlab-cloud-connector gem 配置中的自托管模型单元原语列表中。

如果此文件中缺少该功能，这可能是其无法访问的原因。
可选。如果未列出该功能，您可以通过在 GitLab 实例中设置以下内容来验证这是否是问题的原因：
```
CLOUD_CONNECTOR_SELF_SIGN_TOKENS=1
```
然后重启 GitLab 并检查该功能是否变为可访问。

重要提示：故障排除后，请不要使用此标志设置来重启 GitLab。

请勿在生产环境中使用 CLOUD_CONNECTOR_SELF_SIGN_TOKENS=1。开发环境应与生产环境尽可能保持一致，不应有隐藏的标志或内部专用的变通方法。
要解决此问题：
- 如果您是 GitLab 团队成员，请通过 #g_custom_models Slack 频道联系 Custom Models 团队。
- 如果您是客户，请通过 GitLab 支持报告该问题。