1. AMD 显卡跑 SGLang 推理服务为什么值得折腾如果你手里有一张 AMD 显卡比如 RX 7900 XTX、MI300 系列或者公司机房里的 Instinct 卡想把它变成一台能对外提供 OpenAI 兼容接口的推理服务器那 SGLang 是一个绕不开的选择。SGLang 全称 Structured Generation Language它本质上是一个高性能大模型推理框架核心卖点是 RadixAttention 前缀缓存和连续批处理能在多轮对话、批量相似 prompt 的场景下把 GPU 利用率拉高一大截。它适合谁适合手上有 AMD 硬件、不想被 CUDA 生态绑死、又希望用统一 API 对外提供服务的开发者。但 AMD 这条路和 NVIDIA 不太一样。NVIDIA 上你pip install一把梭基本能跑AMD 上你要面对 ROCm 驱动版本、HSA_OVERRIDE_GFX_VERSION架构覆盖、Docker 设备映射这一堆细节。我自己在 RX 7900 XTX 上从零跑通 SGLang中间踩的坑主要集中在三块容器里认不到 GPU、共享内存不够导致进程被杀、以及服务起来之后外部调用鉴权混乱。前两个是 ROCm 环境问题第三个是接入层问题。这篇笔记就按真实操作顺序来先把 ROCm Docker 环境搭好让容器能看见 AMD 显卡再装 SGLang 并启动服务然后用 TaoToken 的统一 Key 和 API 通道把外部请求接进来做一次 chat completions 验证最后把几个高频报错逐个拆开讲。全程命令和配置都可以直接复制你跟着敲一遍就能得到一台能响应请求的 AMD 推理机。需要提前说明的是TaoToken 在这里扮演的是统一接入层的角色它提供 OpenAI 兼容的 Base URL 和 Key让你不用在每台机器上分别管理各家模型的凭证。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 后面配置里会反复用到。2. ROCm Docker 环境准备与 SGLang 容器启动2.1 主机侧 ROCm 驱动与用户组检查在动 Docker 之前先在宿主机上确认 ROCm 装好了。执行rocminfo | grep gfx正常应该输出类似gfx1100RX 7900 系列或gfx942MI300 系列的架构标识。如果这条命令报 not found说明 ROCm 没装或没进 PATH先去补驱动。版本建议 6.0 以上6.1.x 对 SGLang 的支持更稳。接着确认当前用户在render和video组里。用groups看一眼如果没有这两个组执行sudo usermod -aG render,video $USER改完要重新登录一次 shell 才生效。这一步很多人忽略结果容器里/dev/kfd权限拒绝SGLang 启动时报No AMD GPU detected。2.2 可复制的 docker-compose 配置比起一长串docker run我更推荐用 docker-compose 管理改参数方便。下面这份配置经过实测映射了/dev/kfd和/dev/dri放大了共享内存并注入了架构覆盖变量version: 3.8 services: sglang-amd: image: rocm/pytorch:rocm6.1.2_ubuntu22.04_py3.10_pytorch_release_2.3.0 container_name: sglang-amd devices: - /dev/kfd - /dev/dri group_add: - video cap_add: - SYS_PTRACE security_opt: - seccompunconfined shm_size: 16gb environment: - HSA_OVERRIDE_GFX_VERSION11.0.0 - HIP_VISIBLE_DEVICES0 volumes: - /home/user/models:/app/models ports: - 30000:30000 command: bash -c pip install --no-cache-dir sglang[all] sleep infinity restart: unless-stopped这里HSA_OVERRIDE_GFX_VERSION要按你的卡改RX 7900 XTX 是11.0.0RX 7900 XT 也是11.0.0MI300X 是9.4.2MI250 是9.0.0。填错会直接导致 HIP 初始化失败。shm_size给 16G 是底线大模型 KV Cache 和进程间通信都吃共享内存默认 64M 必崩。2.3 进入容器安装并启动 SGLang 服务docker compose up -d之后docker exec -it sglang-amd bash进容器。先验证 GPU 可见python -c import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))在 ROCm 环境下 PyTorch 仍然用cuda这个命名空间输出True和你的显卡名就对了。然后启动 SGLang 服务端python -m sglang.launch_server \ --model-path /app/models/Llama-3-8B-Instruct \ --host 0.0.0.0 \ --port 30000 \ --tp-size 1 \ --mem-fraction-static 0.88 \ --schedule-policy lpm \ --enable-radix-attention--mem-fraction-static 0.88控制预分配给 KV Cache 的显存比例AMD 卡上给到 0.85 到 0.9 之间比较合适太低会频繁重分配太高容易 OOM。--schedule-policy lpm是最长前缀匹配多轮对话场景命中率高。服务起来后日志里会打印The server is fired up and ready to roll这时候 30000 端口就在监听了。3. TaoToken 统一 Key 接入与 Base URL 配置3.1 为什么要在 SGLang 前面加一层统一接入SGLang 自己起服务后默认是裸的 OpenAI 兼容接口没有鉴权谁都能调。如果你只是本机测试无所谓但一旦要对外或者多项目共用就需要一个统一的 Key 管理和路由层。TaoToken 提供的就是这个一个 Base URL、一个 Key背后可以对接不同模型通道调用格式完全兼容 OpenAI SDK。这样你的客户端代码不用改只换 Base URL 和 Key 就行。先去控制台拿 Key。打开 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建一个 API Key复制出来形如sk-xxxx。这个 Key 就是后面所有请求的凭证。3.2 可复制的环境变量与 settings 片段在容器里或者你的客户端机器上把凭证写成环境变量避免硬编码export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_API_KEYsk-你的实际Key export SGLANG_LOCAL_URLhttp://localhost:30000如果你用的是支持 settings.json 的编辑器插件比如 Cline、Continue 这类配置片段长这样{ models: [ { title: TaoToken Unified, provider: openai, model: gpt-4o-mini, apiBase: https://taotoken.net/api, apiKey: sk-你的实际Key } ] }注意apiBase填的是https://taotoken.net/api不要多加/v1SDK 会自己拼。Model ID 按你实际要调的模型填TaoToken 侧会做路由。如果你是要把本地 SGLang 服务也纳入统一管理可以在 TaoToken 的通道配置里把本地地址注册进去这样外部调用统一走 TaoToken内部转发到你的 AMD 机器。3.3 三件套对照Base URL、Key、Model ID不管你是用 Cline、Codex 的 auth.json还是 Claude Code 的配置核心就三样东西缺一不可配置项值说明Base URLhttps://taotoken.net/api统一入口不带 /v1API Keysk-xxxx控制台创建妥善保管Model ID按需填写如 gpt-4o-mini、claude-3-5-sonnet 等如果你用的是 Codex 的auth.json结构是{ openai: { apiKey: sk-你的实际Key, baseURL: https://taotoken.net/api } }这三件套填对接入基本就通了。填错最常见的是 Base URL 多写了/v1或者漏了https导致 404 或连接失败。4. 验证请求一次 chat completions 打通全链路4.1 用 curl 直接验证服务起来、Key 配好之后先做一次最小验证。用 curl 打 TaoToken 的 chat completions 接口curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [ {role: user, content: 用一句话说明什么是连续批处理} ], max_tokens: 128 }正常返回是一个 JSONchoices[0].message.content里就是模型输出。如果你是把本地 SGLang 注册进 TaoToken 通道那这里返回的就是你 AMD 机器上跑出来的结果。看到choices数组有内容说明全链路通了。4.2 用 Python SDK 验证并打印耗时curl 通了之后用 OpenAI SDK 写个更贴近生产的验证脚本顺便测一下首字延迟import os, time from openai import OpenAI client OpenAI( base_urlos.environ[TAOTOKEN_BASE_URL], api_keyos.environ[TAOTOKEN_API_KEY], ) start time.time() resp client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: 写一个 Python 快速排序}], max_tokens256, ) elapsed time.time() - start print(耗时: %.2fs % elapsed) print(resp.choices[0].message.content)跑通后你会看到耗时和完整代码输出。如果这一步报401说明 Key 不对报Connection error检查 Base URL 和网络报model not found检查 Model ID 拼写。4.3 确认 AMD 显卡真的在干活请求返回了不代表 GPU 在算。回到容器里执行rocm-smi看 GPU 利用率和显存占用。发请求的瞬间利用率会跳起来显存占用稳定在mem-fraction-static设定的比例附近。如果利用率一直是 0说明请求没打到本地 SGLang可能被 TaoToken 路由到别的通道了检查你的通道配置。另外可以在 SGLang 日志里看到Prefill和Decode的批次信息连续批处理生效时日志里会显示动态插入的请求数。这一步确认完你就有了一台真正在 AMD 显卡上跑推理、并且通过统一 Key 对外服务的机器。5. 常见报错排查401、local proxy failed、reading choices、OAuth5.1 401 Unauthorized最常见。原因就三个Key 没传、Key 传错、Key 过期。检查Authorization头是不是Bearer sk-xxx格式中间有空格。如果你用的是环境变量确认echo $TAOTOKEN_API_KEY有值。还有一种情况是 Base URL 写成了https://taotoken.net漏了/api请求打到了首页自然 401。正确写法是https://taotoken.net/api。5.2 local proxy failed这个报错通常出现在你本地配了代理但代理没起来或者端口不对。报错信息类似local proxy failed: connection refused。解决方式是检查你的代理进程是否在跑端口是否和配置一致。如果你没主动配代理检查环境变量HTTP_PROXY、HTTPS_PROXY是不是被别的软件写进去了unset掉再试。注意这里说的是本地网络代理配置问题和任何跨境工具无关纯粹是本地端口连通性排查。5.3 reading choices 相关报错典型信息是Error reading choices: list index out of range或者reading choices。这表示返回的 JSON 里没有choices字段通常是上游返回了错误对象。先打印完整响应体看error字段写了什么。常见原因是 Model ID 不存在或者请求体格式不对比如messages写成了字符串。还有一种是你把max_tokens设得比模型上限还大上游直接拒绝。把max_tokens降到 1024 以内再试。5.4 OAuth 相关报错如果你用的是 Claude Code 这类工具可能会遇到OAuth token expired或invalid_grant。这类工具默认走 OAuth 流程但接入 TaoToken 时应该用 API Key 模式。检查你的配置文件里是不是还留着旧的 OAuth 字段把它删掉改成apiKeybaseURL三件套。Claude Code 的配置里 Base URL 填https://taotoken.net/apiKey 填sk-xxxModel ID 按需填重启工具即可。5.5 容器内 GPU 不可见这个不算 API 报错但很致命。容器里rocminfo报No GPU found检查三处--device/dev/kfd和/dev/dri有没有映射用户有没有在video组HSA_OVERRIDE_GFX_VERSION有没有填对。三个都对还不行升级 ROCm 驱动到 6.1 以上。6. 长期编码与 Agent 场景的接入建议如果你只是偶尔跑一次验证上面这套够了。但如果你打算把 AMD 推理机长期用作编码助手或者 Agent 后端有几个点值得提前规划。第一是并发SGLang 的连续批处理在 16 并发以上收益明显但前提是mem-fraction-static别设太高留出动态分配空间。第二是 Key 轮换TaoToken 控制台可以创建多个 Key给不同项目分配不同 Key方便审计和吊销。对于长期编码场景建议走 Coding Plan 通道入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它针对代码补全和 Agent 调用做了路由优化。模型对话类的轻量验证可以直接用 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 快速试。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 遇到参数不确定的时候翻一下比猜快。最后说一个实测经验AMD 卡上跑 SGLang第一次启动会编译 HIP kernel耗时可能三五分钟别以为卡死了。编译缓存落在容器内如果你用--rm启动下次还得重编。用 docker-compose 持久化容器或者把缓存目录挂出来能省不少时间。服务稳定后rocm-smi里 GPU 利用率长期在 60% 以上说明批处理调度在正常工作如果长期低于 20%检查是不是并发太低或者schedule-policy没设成lpm。