如何在Linux服务器上搭建大模型API统一接入服务?

发布人:A5数据发布时间:2026-11-16 10:20阅读量:15

大模型 API 统一接入服务可以部署在一台 Linux 服务器上:由网关接收符合 OpenAI API 格式的请求,再根据模型别名转发到对应的模型服务商。下面以 LiteLLM Proxy、Docker Compose 和 Ubuntu 22.04/24.04 为例,搭建一个不依赖数据库的最小可用版本。首次部署只需准备一个上游服务商的 API 密钥;客户端使用网关密钥访问,服务商密钥则保存在服务器端。

这套配置适合先验证请求链路、统一客户端调用地址的场景。示例将网关端口限制在本机回环地址,避免未经 HTTPS 保护的 API 直接暴露到公网;如果需要远程访问,可在后面增加 Nginx HTTPS 接入。无数据库的简化部署不提供完整的团队级密钥管理、用量统计和配额控制。

A5idc数据提供中国香港、美国、日本、韩国、中国台湾、新加坡及马来西亚等地区的物理服务器,可为 Linux 上的模型 API 接入网关提供部署资源。不同产品系列涵盖多种 CPU、内存、SSD 或 NVMe 存储与网络线路选择,适用于承载接口服务及相关业务后台;多地区资源也为面向不同区域的服务部署提供基础。

一、准备条件

开始前确认以下条件:

  • 一台可访问互联网的 Linux 服务器,本文命令以 Ubuntu 22.04/24.04 为例。
  • 已安装 Docker Engine 和 Docker Compose v2。先检查版本:
docker --version
docker compose version

如果当前账号没有权限访问 Docker,可在命令前加 sudo。不要为了方便而忽略 Docker 权限的安全影响:拥有 Docker 管理权限的账号通常可以获得较高的主机控制能力。

  • 服务器可以访问所选模型服务商的 API。
  • 已取得该服务商的 API 密钥,并确认账户有权调用选定模型。
  • 若要通过域名提供远程 HTTPS 服务,还需准备指向服务器的域名,以及可供 Nginx 使用的有效 TLS 证书。

本文示例使用一个 OpenAI 兼容的服务商作为上游。模型名称和 API 密钥需要根据实际服务商账号调整;不同服务商支持的模型标识、接口格式和访问区域可能不同。

二、创建部署目录并配置密钥

创建独立目录,避免把配置和密钥散落在系统路径中:

mkdir -p ~/llm-gateway
cd ~/llm-gateway

在目录中创建 .env 文件:

nano .env

填入以下内容,并将占位文本替换为实际密钥:

LITELLM_MASTER_KEY=sk-请替换为随机生成的网关密钥
OPENAI_API_KEY=请替换为服务商提供的API密钥

这里有两类密钥,不要混用:

  • LITELLM_MASTER_KEY:客户端访问网关时使用。
  • OPENAI_API_KEY:网关调用上游模型服务时使用,不应交给客户端。

网关密钥可使用随机值生成,例如:

openssl rand -hex 32

将生成结果加上 sk- 前缀后填入配置。限制密钥文件权限:

chmod 600 .env

不要将 .env 上传到代码仓库、公开日志或工单附件。若密钥曾经泄露,应在对应服务商后台撤销旧密钥并重新生成,再更新服务器配置。

三、定义模型别名和服务容器

创建 config.yaml:

nano config.yaml

写入如下配置:

model_list:
  - model_name: chat-default
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY

model_name 是客户端请求时使用的别名;litellm_params.model 是网关传给上游的模型标识。若服务商不支持示例模型,替换为账号中可用的模型名称,并根据服务商要求调整前缀或适配方式。别名只负责统一客户端调用入口,不代表模型能力、价格或可用性相同。

随后创建 compose.yaml:

nano compose.yaml

配置如下:

services:
  litellm:
    image: ghcr.io/berriai/litellm:main-latest
    command:
      - "--config"
      - "/app/config.yaml"
      - "--host"
      - "0.0.0.0"
      - "--port"
      - "4000"
    env_file:
      - .env
    volumes:
      - ./config.yaml:/app/config.yaml:ro
    ports:
      - "127.0.0.1:4000:4000"
    restart: unless-stopped

端口映射左侧的 127.0.0.1 表示只允许服务器本机访问 4000 端口,后续可由同机 Nginx 转发 HTTPS 请求。不要在未配置 HTTPS 和访问控制时,直接将此端口改为公网可访问。

三、定义模型别名和服务容器配图

示例使用可变镜像标签,适合快速验证,不利于长期复现。正式运行时应选定经过验证的 LiteLLM 版本,并固定到具体版本标签或镜像摘要;升级前备份配置并安排验证窗口。

检查文件是否齐全:

ls -l

应能看到 compose.yaml、config.yaml 和 .env。检查 YAML 缩进时使用空格,不要混入制表符;.env 中的密钥等号两侧不要添加空格。

四、启动服务并检查运行状态

先在后台启动容器:

docker compose up -d

查看容器状态:

docker compose ps

若状态为 Up,继续查看最近启动日志:

docker compose logs --tail=100 litellm

日志中不应持续出现配置解析错误、缺少环境变量或端口绑定失败。需要持续观察时可执行:

docker compose logs -f litellm

按 Ctrl+C 只会结束日志跟随,不会停止容器。

再检查本机健康接口:

curl -i http://127.0.0.1:4000/health/liveliness

若服务正常启动,通常会返回成功状态码。不同版本的健康接口可能存在差异;若该路径返回 404,可查看所用版本的健康检查接口说明,或先以容器状态、启动日志和后续 API 请求共同判断,不要仅凭健康检查路径失败就认定服务未启动。

五、验证模型列表和实际调用

健康接口成功只能说明服务进程可响应,不能证明上游模型请求可用。还需分别测试网关鉴权和模型调用。

五、验证模型列表和实际调用配图

在当前终端加载 .env 中的变量:

set -a
. ./.env
set +a

查询网关暴露的模型列表:

curl -sS http://127.0.0.1:4000/v1/models \
  -H "Authorization: Bearer ${LITELLM_MASTER_KEY}"

结果中应能找到配置的别名 chat-default。如果接口返回 401,优先检查请求使用的网关密钥是否与 LITELLM_MASTER_KEY 一致;不要把上游服务商密钥误填到请求头中。

接着发送一次聊天请求:

curl -sS http://127.0.0.1:4000/v1/chat/completions \
  -H "Authorization: Bearer ${LITELLM_MASTER_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chat-default",
    "messages": [
      {
        "role": "user",
        "content": "请用一句话说明API网关的作用。"
      }
    ]
  }'

成功时,响应应包含模型回复以及类似 choices 的结果字段。以下为格式示例,不代表实际调用结果:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "API网关负责接收请求并将其转发到对应的服务。"
      }
    }
  ]
}

验证时重点确认三件事:请求地址是网关而非上游服务商地址;请求中的 model 使用网关别名;鉴权头使用网关密钥。后续客户端只需维护网关地址和网关密钥,上游密钥由服务器端配置管理。

六、需要远程访问时启用 HTTPS

如只在服务器本机测试,可暂时不配置 Nginx。若客户端需要从其他机器访问,应先确认域名解析到服务器,并准备好有效证书。确保 compose.yaml 仍将 4000 绑定到 127.0.0.1,再由 Nginx 监听 HTTPS 并转发到本机服务。

六、需要远程访问时启用 HTTPS配图

创建 Nginx 站点配置,例如 /etc/nginx/sites-available/llm-gateway:

server {
    listen 443 ssl;
    server_name api.example.com;

    ssl_certificate     /etc/ssl/certs/api.example.com.crt;
    ssl_certificate_key /etc/ssl/private/api.example.com.key;

    location / {
        proxy_pass http://127.0.0.1:4000;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_buffering off;
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}

将 api.example.com 和证书路径替换为实际值。启用配置前先备份已有同名文件,避免覆盖正在使用的站点配置;再创建链接并检查语法:

sudo ln -s /etc/nginx/sites-available/llm-gateway \
  /etc/nginx/sites-enabled/llm-gateway
sudo nginx -t

只有在 nginx -t 检查通过后,才重新加载 Nginx:

sudo systemctl reload nginx

从允许访问的客户端测试 HTTPS 地址:

curl -i https://api.example.com/health/liveliness

远程请求时,将 URL 中的本机地址替换为 https://api.example.com。网络安全组或主机防火墙只开放必要的 HTTPS 入口;不要同时开放未经 HTTPS 保护的 4000 端口。证书文件权限应限制为服务所需,不要公开私钥。

七、常见失败处理

表现优先检查判断与处理
容器没有启动或反复重启docker compose ps、docker compose logs --tail=100 litellm常见原因包括 YAML 格式错误、配置路径不正确、镜像拉取失败或必需环境变量缺失。先修正配置,再执行 docker compose up -d。
健康接口无法连接容器状态、日志、端口映射若容器未运行,先处理启动错误;若容器运行但本机连接失败,检查端口是否绑定在 127.0.0.1:4000,以及是否有其他进程占用端口。
/v1/models 返回 401.env 中的网关密钥、请求头请求头必须使用 LITELLM_MASTER_KEY。更新 .env 后重新创建容器,使新环境变量生效。
请求提示模型不存在或不支持请求中的模型别名、config.yaml请求应使用 chat-default;配置中的上游模型名称则应与服务商支持的模型标识匹配。修改后重启服务并重新检查模型列表。
上游返回鉴权错误OPENAI_API_KEY、服务商账户权限确认上游密钥有效、未过期,并有权调用配置的模型。不要用网关密钥替代服务商密钥。
上游请求超时或连接失败服务器出站网络、服务商 API 地址和区域限制检查服务器能否访问服务商所需接口,以及 DNS、出站策略和服务商侧限制。若网关本身健康但调用失败,问题通常位于上游连通性或账户配置。
Nginx 返回 502Nginx 错误日志、网关本机端口检查 LiteLLM 容器是否运行,以及 proxy_pass 地址和端口是否与容器映射一致。
HTTPS 证书报错域名、证书路径、证书有效期确认域名与证书匹配、证书文件可读,并在重新加载前运行 sudo nginx -t。

修改 config.yaml 后,容器不会因为文件变更而自动保证配置已加载。首次部署阶段可在确认改动后执行:

docker compose restart litellm

如果调整了 Compose 文件或容器环境变量,使用:

docker compose up -d

完成后重复检查容器状态、健康接口、模型列表和聊天请求。密钥更改后也应使用新密钥重新执行鉴权验证。

八、验收与回滚检查项

验收时逐项确认:

  • docker compose ps 显示网关容器正常运行,启动日志没有持续报错。
  • 本机健康接口可以响应。
  • /v1/models 通过网关密钥鉴权,并返回配置的模型别名。
  • /v1/chat/completions 能通过网关返回上游模型响应。
  • 客户端不需要接触上游服务商密钥。
  • 如已启用远程访问,HTTPS 证书有效,Nginx 配置检查通过,公网未开放明文网关端口。
  • .env 权限受限,配置和密钥的备份位置也受到保护。

首次部署尚未承载业务时,可通过停止容器回滚:

cd ~/llm-gateway
docker compose down

此命令停止并移除 Compose 创建的容器和网络,不会删除当前目录中的 .env 和配置文件。若同时配置了 Nginx,应先恢复启用前备份的站点文件,再检查并重新加载:

sudo nginx -t
sudo systemctl reload nginx

不要在没有确认影响范围和备份的情况下删除配置文件、密钥文件或其他站点配置。回滚后再次执行 docker compose ps,确认网关已停止;从外部检查时,也应确认域名不再转发到该服务。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/9705.html

相关推荐