灵息 AI 文档

Appearance

接入到 MoFox (一键包) ​

MoFox 是一个强大的QQ机器人框架，本教程将引导您如何在 MoFox 中配置 灵息 API。MoFox 的模型配置采用 TOML 格式，分为“供应商”、“中转（模型映射）”和“具体应用”三个部分。

1. 配置 API 供应商 (api_providers) ​

打开 MoFox 的模型配置文件（通常在 core/Bot/config/model_config.toml），在 [[api_providers]] 部分添加灵息 API。

toml
[[api_providers]]
name = "LingXi"                              # 供应商名称，可自定义
base_url = "https://ask.ling.rest/api/v1"    # 灵息 API 地址
api_key = "sk-xxxxxx"                        # 您的灵息 API Key
client_type = "openai"                       # 灵息完全兼容 OpenAI 格式
max_retry = 2                                # 最大重试次数
timeout = 30                                 # 超时时间（秒）

⚠️ 核心注意

  • Base URL: 必须是 https://ask.ling.rest/api/v1，末尾不要加斜杠。
  • client_type: 必须填写 "openai"，即使您使用的是 Gemini 模型，灵息也已为您做好了 OpenAI 格式适配。

2. 配置模型中转 (models) ​

在 [[models]] 部分，将灵息的模型标识符映射为 MoFox 内部使用的名称。

toml
[[models]]
model_identifier = "gemini-3-flash-preview-vertex"  # 灵息平台提供的模型 ID
name = "lingxi-gemini"                              # 您给模型起的别名
api_provider = "LingXi"                             # 必须对应上面供应商的 name

提示

  • 您可以前往 模型名获取 页面查看灵息支持的所有模型 ID。
  • model_identifier 必须与灵息文档中的 ID 完全一致（全小写，横杠连接）。

3. 应用模型 (model_task_config) ​

在配置文件的最后，将映射好的模型名称应用到具体的任务中（如聊天、思考、情感分析等）。

toml
[model_task_config.replyer]
model_list = ['lingxi-gemini']    # 使用您在第二步定义的 name
temperature = 0.7
max_tokens = 2000

[model_task_config.planner]
model_list = ['lingxi-gemini']

4. 常见问题排查 ​

  • 报错 403/401：
    • 检查 api_key 是否填写正确。
    • 检查 base_url 是否包含了 /api/v1。
  • 找不到模型 (Could not find model)：
    • 检查 model_task_config 中填写的模型名称是否在 [[models]] 的 name 中定义过。
    • 检查 api_provider 的名称是否与 [[api_providers]] 的 name 一一对应。
  • AFC 系统建立标签失败：
    • 在初次启动时，MoFox 会请求模型生成人格标签。如果此时报错，通常是因为 API 请求过快触发了限流，建议使用更稳定的 Vertex 系列模型进行初始化。

💡 进阶建议

如果您在配置过程中遇到困难，可以使用我们的 API 测试场 先验证您的 Key 和地址是否正常，排除网络和服务商因素后再进行 MoFox 内部配置。