Nature Skills 接入 OpenAI 兼容接口的配置方法

如果你在 Nature Skills 里需要把默认模型换成本地服务或第三方 OpenAI 兼容 API，核心工作不是改界面，而是确认模型地址和密钥在哪里生效。大多数这类系统会同时支持环境变量和配置文件，但入口不同，改错位置就会出现“配置了但没生效”的情况。下面按配置入口、认证参数、模型字段、验证脚本和错误排查五个环节展开。

这条路径适用于已确认目标服务支持 OpenAI 兼容 /v1/chat/completions 接口的用户。操作动作是：先定位 config 或 .env 中的模型服务字段，再设置 OPENAI_BASE_URL 与 OPENAI_API_KEY，最后用 3-5 行 Python 脚本验证连通性。风险边界在于：不同服务商的模型名称、路径前缀和超时行为可能有差异，需要结合目标服务实际文档确认，不能假设所有兼容接口行为完全一致。

定位服务配置入口

先不要急着改代码。以常见的开源项目为例，模型服务地址通常集中在 .env 或 config.yaml 里。打开项目根目录，先找这两个文件，如果都没有，再用 grep -ri "openai\|api_base\|model" 在源码里搜一下。

建议重点查找以下字段名：

OPENAI_BASE_URL 或 API_BASE
OPENAI_API_KEY
MODEL 或 DEFAULT_MODEL
model_provider、llm_config 这类嵌套配置

如果项目内置了 Web 管理后台，入口也可能在“模型设置”或“服务商配置”页面里。记住一个原则：只要看到“Provider”“Base URL”“Model”“API Key”这几个词，就是你需要改动的位置。不要把密钥写进前端页面或提交到 Git 仓库，尽量保留在服务端环境变量中。

设置 API 地址与密钥

最常见的方式是通过环境变量注入。以下示例适用于大多数 OpenAI SDK 兼容项目：

export OPENAI_BASE_URL="https://your-provider.example.com/v1"
export OPENAI_API_KEY="sk-your-key-here"

如果项目使用 .env 文件，则在文件中写入同样的键值对。注意 BASE_URL 是否以 /v1 结尾：有的服务商要求带 /v1，有的要求填根域名，填错之后 404 是常态。建议先按服务商文档给出的完整地址原样填入，不要自己拼接。

另外，如果用 Docker 部署，可以在 docker run 命令里通过 -e 参数传入：

-e OPENAI_BASE_URL=https://your-provider.example.com/v1 -e OPENAI_API_KEY=sk-xxx

设置完成后必须重启项目进程，环境变量属于进程级配置，不重启不会生效。

配置模型名称与请求参数

地址和密钥只解决“往哪里发”和“怎么认证”的问题，真正决定本次请求用什么模型的是 model 字段。在配置文件或环境变量里找到类似 MODEL_NAME、DEFAULT_MODEL 的项，填目标服务商提供的模型 ID，比如 gpt-4o-mini、qwen-plus 或本地部署的 llama-3.1-8b。模型 ID 必须与目标服务商实际返回的可用列表一致，大小写也敏感。

请求参数也需要留意。以 OpenAI SDK 为例，常用参数如下：

{
  "model": "gpt-4o-mini",
  "temperature": 0.7,
  "max_tokens": 512
}

temperature 控制输出随机性，0 到 2 之间，数值越高越自由，但同一模型的合理范围未必相同，建议先用服务商默认值。超时和重试通常在客户端初始化时设置，Python 例子：

client = OpenAI(
    base_url="https://your-provider.example.com/v1",
    api_key="sk-xxx",
    timeout=30.0,
    max_retries=2
)

超时时间不能设得太短，大模型生成一个长回复时，首字返回时间往往超过 10 秒。重试次数建议保留 1-2 次，避免临时网络抖动导致整个任务中断。

用最小请求验证连通性

跑完整任务之前，先花十几秒验证地址和密钥是否可用。以下是 4 行 Python 代码，可以直接复制到项目所在环境执行：

from openai import OpenAI
client = OpenAI(base_url="https://your-provider.example.com/v1", api_key="sk-xxx")
resp = client.chat.completions.create(model="gpt-4o-mini", messages=[{"role":"user","content":"ping"}])
print(resp.choices[0].message.content)

如果环境里没有安装 openai 库，先执行 pip install openai。这段代码只发送一个“ping”文本，目的是确认三件事：地址可以路由、密钥能通过认证、指定模型真实存在。如果返回内容或报错码能看到，就说明链路是通的，再回到 Nature Skills 跑真实任务。

排查常见认证与路由错误

验证请求失败时，优先看返回码和响应体，不要只盯着“连接失败”。以下是一份常用对照表：

401 Unauthorized：密钥错误或格式不对。
403 Forbidden：密钥有效但无权访问该模型，或账号余额/权限受限。
404 Not Found：请求路径不对，最常见是 base_url 缺少 /v1，或接口路径不含 /chat/completions。
422 Unprocessable Entity：请求体参数不合法，检查 model 名称和参数类型。
429 Too Many Requests：触发速率限制，稍后重试或降低并发。

要捕获实际请求路径，可以在 Python 脚本里临时开启 debug：

import logging
logging.basicConfig(level=logging.DEBUG)

运行后日志会打印出完整请求 URL 和状态码。拿到这个 URL 后，把它与服务商文档里的接口地址做逐字符比对，大多数 404 都能在这里发现。