当本地同时运行多个AI服务并且希望用同一个Web界面访问,但各个服务的API格式与鉴权策略不一致时,就需要在统一入口做一层分发与鉴权转换。这个分发层不是必须的,如果你的Web界面本来就能同时配置多个后端地址,那直接配置即可。
以我自己常用的组合为例:Stable Diffusion WebUI默认监听7860端口,Ollama监听11434端口。如果前端只认一个OpenAI兼容地址,就要在中间加一个代理。代理层可以做在Nginx里,也可以用一段简单的FastAPI程序,具体看你对HTTP控制粒度的要求。
先判断要不要自己加一层分发
在动手之前,先看统一Web界面是否支持多后端配置。Open WebUI可以添加多个OpenAI兼容上游,虽然它主要面向语言模型,但绘画接口也可以作为自定义API挂上去;NextChat则是通过环境变量指定一个目标地址。只有当界面只支持一个后端地址,或者你希望把服务统一暴露给局域网、避免记住多个端口时,才有必要自建分发。如果只是本机自己用,多开几个标签页反而更省事。
界面版本不同,多上游配置方式也不同。有的Open WebUI版本只认一个OPENAI_API_BASE_URL,这种情况下就必须在外部做聚合。需要结合当前版本的界面配置项确认。
路由怎么分才不打架
路由设计的关键不是简单按路径分,而是要把每个后端服务的API语义映射到统一入口上。绘画服务通常是 /sdapi/v1/...,语言模型通常是 /v1/models 和 /v1/chat/completions,分发层需要同时识别路径和HTTP方法。
例如Ollama的OpenAI兼容接口是 /v1/chat/completions,而Stable Diffusion WebUI的接口是 /sdapi/v1/txt2img。这两类接口在路径前缀上就能区分开。但如果语言模型网关用了 /api/v1 这种前缀,绘画服务又使用了 /api/v1/caption,那就会冲突。所以我建议在统一入口处重新定义前缀,把语言模型固定为 /v1,绘画固定为 /sdapi,然后用Nginx location精确匹配。
location /v1/ {
proxy_pass http://127.0.0.1:11434;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
location /sdapi/ {
proxy_pass http://127.0.0.1:7860;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}这段配置放在Nginx的server块中。执行位置是Nginx配置文件,通常是 /etc/nginx/conf.d/ 下。生效前先运行 nginx -t 检查语法,再执行 nginx -s reload。验证方式很简单:分别请求 /v1/models 和 /sdapi/v1/sd-models,看返回的是不是对应服务的内容。如果返回404,先检查实际后端路径里是否包含这些前缀,有的服务内部路由是 /api/v1,需要相应调整 location 的匹配路径。
鉴权头怎么处理才不出错
鉴权分发有一个容易踩的坑:统一界面往往只把一份API key传给后端,可绘画和语言模型可能用不同的key,甚至一个要key一个不用。不能原样透传,需要先截获请求中的认证头,按路由规则替换成目标服务认可的凭证。
我遇到过的典型情况是:Ollama本身不校验Authorization,但某些OpenAI兼容插件要求填一个固定的key;而SD WebUI没有开鉴权时,如果你把前端的Authorization透传过去,后端可能直接忽略,也可能因为多余的头报错。所以需要在分发层做“头替换”而不是“透传”。下面是一个FastAPI中间件的最小实现:
from fastapi import FastAPI, Request
import httpx
app = FastAPI()
ROUTES = {
"/v1/": {"url": "http://127.0.0.1:11434", "key": "ollama-secret"},
"/sdapi/": {"url": "http://127.0.0.1:7860", "key": None},
}
@app.api_route("/{path:path}", methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"])
async def proxy(path: str, request: Request):
for prefix, conf in ROUTES.items():
if path.startswith(prefix):
headers = dict(request.headers)
headers.pop("host", None)
if conf["key"]:
headers["Authorization"] = f"Bearer {conf['key']}"
else:
headers.pop("Authorization", None)
target_url = conf["url"] + "/" + path
async with httpx.AsyncClient() as client:
resp = await client.request(
request.method,
target_url,
headers=headers,
params=request.query_params,
content=await request.body(),
)
return resp.content, resp.status_code, dict(resp.headers)
return {"error": "not found"}, 404这段代码的作用是:根据路径前缀选择目标地址和对应的key;有key就替换Authorization,没有key就把Authorization头删掉。执行位置是启动FastAPI服务的机器,通常监听8000端口。验证方式是用curl带不同的key请求不同前缀,看后端日志中收到的Authorization头是否符合预期。容易出问题的是OPTIONS预检请求——很多前端会在跨域时先发OPTIONS,需要在代理中直接响应预检,或者交给Nginx处理。
另外,如果你有两个语言模型上游都要用 /v1 前缀,但一个需要key A,一个需要key B,而请求里只有一个key,那只能根据请求体里的模型名再次分流。比如读取JSON里的 model 字段,再决定转发目标和key。这种做法需要特别注意请求体可能很大,不能简单读一次后丢失,要缓存或者使用流式读取。
验证与常见的边界检查
路由和鉴权改完,至少要做下面几个检查:
- 用curl分别测试不带key、带错误key、带正确key的请求,观察返回码是200、401还是404。
- 查看Nginx访问日志和后端服务日志,确认请求确实到达,并且代理没有吞掉原始客户端IP和请求头。
- 对语言模型接口测试流式输出。Nginx默认会缓冲响应,导致SSE无法实时刷新,需要在
location /v1/里增加proxy_buffering off;和合适的超时时间。 - 对绘画接口测试大图输出。txt2img请求耗时长,如果Nginx的
proxy_read_timeout默认60秒,很可能超时,建议按任务长短调整到300秒以上。 - 回滚边界:修改前备份原配置文件,保存一份当前生效版本。如果发现异常,直接恢复备份并重新加载。
下面给出两组常用的curl请求,用来验证分发是否正确:
curl -i -H "Authorization: Bearer ollama-secret" http://127.0.0.1:8000/v1/modelscurl -i http://127.0.0.1:8000/sdapi/v1/sd-models第一组命令会请求语言模型路由,预期返回Ollama模型列表;第二组请求绘画路由,预期返回SD模型列表,且响应头里不应该有额外的认证错误。如果第二个命令返回401,说明后端实际上开启了鉴权,此时需要在ROUTES里给 /sdapi/ 配置key,而不是直接删掉。具体要看Stable Diffusion WebUI启动参数,比如是否带了 `--api-auth`,这个可以直接从进程启动命令里确认。
上述分层方案不复杂,但每一步都会受具体版本影响。Nginx不同版本对location匹配的优先级略有差异,FastAPI版本和httpx接口也可能变化。所以不要把上面的配置当成万能模板,先在实际环境里跑通,再决定要不要固化。