Ulnvault 使用手册

1. 系统概述

1.1 什么是 Ulnvault

Ulnvault 是一个统一的 AI 模型聚合网关（Unified AI Model Aggregation Gateway），其核心功能包括：

• 多厂商聚合：在售 60 个模型，覆盖 OpenAI、Anthropic（Claude）、Google（Gemini）、xAI（Grok）、Meta Llama、Amazon Bedrock、Mistral、Cohere、DeepSeek、Moonshot（Kimi）、通义千问 Qwen、腾讯混元、智谱 GLM、NVIDIA、小米 MiMo、MiniMax、Sakana 等 18 家厂商
• 统一 API 接口：将不同提供商的 API 转换为统一的 OpenAI/Claude/Gemini 兼容格式，开发者无需修改代码即可切换模型
• Token 管理：支持创建和管理 API Token，便于调用和计费
• UAP 平台（Ulnvault Agent Platform）：AI Agent 实例部署与管理，主推 UlnClaw（开源个人 Agent）、同时支持 ZeroClaw 等运行时
• 口袋秘书 App（移动端）：手机端随时对话与查看用量，与网页控制台同账号
• 模型定价：官方最新价 +10% 的透明定价体系，按量计费（详见第 8 章）
• Playground：在线测试和体验各种模型

1.2 架构特点

• 网关模式：Ulnvault 作为中间层，将客户端请求转发到上游 AI 提供商
• 统一认证：使用 API Token 进行身份验证
• 按量计费：根据实际使用量进行计费，支持配额管理和限额控制
• 多格式兼容：支持 OpenAI、Claude、Gemini 等多种 API 格式

2. 快速开始

2.1 注册与登录

注册新账户

登录

1. 访问登录页面，输入用户名和密码
2. 如开启两步验证（2FA），需要输入验证码
3. 点击「登录」进入控制台

第三方 OAuth 登录

Ulnvault 支持以下第三方平台登录：

• GitHub
• Discord
• Telegram
• 微信（WeChat）

点击相应的第三方登录按钮，按提示完成授权绑定。

2.2 获取 API Key

2.3 快速验证

使用 curl 验证您的 API Key 是否可用：

curl https://ai.ulnit.com/v1/models \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

成功响应示例：

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4",
      "object": "model",
      "created": 1687882411,
      "owned_by": "openai"
    }
  ]
}

3. 控制台使用

3.1 仪表盘（Dashboard）

登录后首先看到的是仪表盘，显示以下信息：

• 账户余额：当前账户剩余配额
• 使用统计：API 调用量、Token 消耗等
• 最近调用：最近的 API 调用记录
• 订阅状态：当前订阅计划信息

3.2 令牌管理（Token Management）

查看令牌列表

显示所有已创建的 API Token，包括：

编辑令牌

点击令牌对应的「编辑」按钮可以修改：名称、配额设置、过期时间、模型限制。

查看令牌密钥

点击「查看 Key」按钮，在验证身份后可查看完整的 API Key。

3.3 充值与账单

充值：进入「充值」页面 → 选择金额或输入自定义金额 → 选择支付方式（支付宝、微信支付，由 Epay 网关承载）→ 完成支付。充值成功后，余额将自动添加到账户。

账单记录：在「账单」页面可以查看充值记录、消费明细、发票信息。

订阅管理：进入「订阅」页面 → 查看可用的订阅计划 → 选择适合的计划并进行订阅。订阅成功后，系统将按计划自动扣费。

3.4 用户设置

在「设置」页面可以：

• 修改个人信息（用户名、邮箱等）
• 修改密码
• 启用或禁用两步验证（2FA）
• 管理 Passkey 密钥
• 管理第三方账号绑定（GitHub、Discord 等）
• 配置通知偏好

4. API 调用指南

4.1 API 基础信息

4.2 聊天完成接口（Chat Completions）

OpenAI 兼容格式

curl 示例：

curl https://ai.ulnit.com/v1/chat/completions \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [
      {"role": "user", "content": "你好，请介绍一下你自己"}
    ],
    "temperature": 0.7
  }'

Python 示例：

import requests

url = "https://ai.ulnit.com/v1/chat/completions"
headers = {
    "Authorization": "Bearer sk-YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "model": "gpt-4",
    "messages": [
        {"role": "user", "content": "你好，请介绍一下你自己"}
    ],
    "temperature": 0.7
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

JavaScript 示例：

const response = await fetch('https://ai.ulnit.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk-YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gpt-4',
    messages: [{ role: 'user', content: '你好，请介绍一下你自己' }],
    temperature: 0.7
  })
});
const data = await response.json();
console.log(data);

Claude 格式

curl https://ai.ulnit.com/v1/messages \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [{"role": "user", "content": "你好"}],
    "max_tokens": 1024
  }'

Gemini 格式

curl https://ai.ulnit.com/v1beta/models/gemini-pro:generateContent \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "你好"}]}]
  }'

4.3 其他接口

获取模型列表

curl https://ai.ulnit.com/v1/models \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

Embeddings（文本嵌入）

curl https://ai.ulnit.com/v1/embeddings \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "text-embedding-3-small", "input": "这是测试文本"}'

图像生成

curl https://ai.ulnit.com/v1/images/generations \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "dall-e-3", "prompt": "一只可爱的猫咪", "n": 1, "size": "1024x1024"}'

语音转文字（Transcription）

curl https://ai.ulnit.com/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -F "file=@audio.mp3" \
  -F "model=whisper-1"

文字转语音（Speech）

curl https://ai.ulnit.com/v1/audio/speech \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "tts-1", "input": "你好，这是测试语音", "voice": "alloy"}' \
  -o speech.mp3

4.4 流式响应

添加 "stream": true 参数启用流式输出：

curl https://ai.ulnit.com/v1/chat/completions \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "请讲一个故事"}],
    "stream": true
  }'

4.5 错误处理

错误响应示例：

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

5. UAP Agent 平台

UAP（Ulnvault Agent Platform）是 Ulnvault 提供的 AI Agent 实例部署与管理平台，允许用户创建、运行和管理自己的 AI Agent 容器。当前平台主推 UlnClaw（开源个人 Agent，见 https://gitee.com/ushaw/ulnclaw），同时支持 ZeroClaw 等运行时（内部路由与表名仍沿用 oap 前缀，不影响使用）。

5.1 访问 UAP 控制台

登录后，在导航栏中找到「UAP」或「Agent 平台」入口，点击进入。

5.2 创建 Agent 实例

5.3 管理实例

实例列表

实例操作

访问 Agent

实例创建并启动后，可以通过以下方式访问：

• 代理 URL（推荐）：/api/oap/agent/{tenant_id}/ — 带鉴权和自动唤醒功能
• 直接 URL：通过宿主机器端口直接访问（外部工具使用）
• 快捷入口：/agent — 自动重定向到您当前运行的实例

5.4 流量监控

UAP 控制台显示每个实例的入站流量（Bytes In）和出站流量（Bytes Out）。根据您的订阅计划，可能有流量限额，超出限额会产生额外费用或限速。

6. 模型广场

模型广场展示了 Ulnvault 支持的所有 AI 模型及其定价信息。

6.1 浏览模型

访问「模型广场」或「Pricing」页面可以查看模型列表、模型分组、模型描述和定价信息。

6.2 在售模型示例

模型广场在售 60 个模型，覆盖 OpenAI、Anthropic（Claude）、Google（Gemini）、xAI（Grok）、 Meta Llama、Amazon Bedrock、Mistral、Cohere、DeepSeek、Moonshot（Kimi）、通义千问 Qwen、腾讯混元、 智谱 GLM、NVIDIA、小米 MiMo、MiniMax、Sakana 等 18 家厂商。示例（价格 = 我方售价，为厂商官方最新价 +10%）：

最新模型与完整价格请以「模型广场」页面为准。

6.3 筛选和搜索

可使用筛选器：按供应商（OpenAI、Anthropic、Google 等）、按能力（聊天、Embeddings、图像、音频）、按分组（根据用户组筛选可用模型）。

7. 常见问题

7.1 账户和登录

Q: 忘记密码怎么办？
A: 在登录页面点击「忘记密码」，输入注册邮箱，系统将发送密码重置链接。

Q: 如何启用两步验证（2FA）？
A: 进入「设置」→「安全设置」，点击「启用 2FA」，按照指引使用认证应用绑定。

Q: 支持哪些第三方登录？
A: 支持 GitHub、Discord、Telegram、微信等 OAuth 登录方式。

7.2 API 使用

Q: API Key 格式是什么？
A: 格式为 sk- 开头，后跟随机字符串。

Q: 为什么 API 调用失败？
A: 常见原因有 API Key 无效或已过期、账户余额不足、请求频率超限、模型不可用或已下架。

Q: 如何查看 API 使用量？
A: 在「仪表盘」或「令牌管理」页面可查看使用统计，或调用 /usage/token 接口。

Q: 支持流式输出吗？
A: 支持，在请求中设置 "stream": true 即可启用 SSE 流式响应。

Q: 支持哪些 API 格式？
A: 支持 OpenAI 格式、Claude 格式（/v1/messages）、Gemini 格式。

7.3 计费和充值

Q: 如何充值？
A: 在「充值」页面选择金额和支付方式完成支付。

Q: 订阅计划可以取消吗？
A: 可以，在「订阅」页面取消，取消后将在当前计费周期结束后失效。

Q: 账户余额可以退款吗？
A: 请联系客服处理退款申请。

7.4 UAP 平台

Q: 创建 UAP 实例需要什么条件？
A: 需要有效的订阅计划，系统会根据计划自动分配资源。

Q: Agent 实例可以创建多少个？
A: 根据您的订阅计划，不同计划有不同的实例数量限制。

Q: Agent 实例需要一直运行吗？
A: 不需要，可以随时停止以节省资源。停止后会释放资源但保留配置。

Q: 如何为 Agent 更换 API Token？
A: 在实例详情页点击「绑定 Token」，选择新的 Token 即可。

8. 费率说明

8.1 计费方式

Ulnvault 采用按量计费模式：用户预先充值到账户 → API 调用时按模型定价实时扣除配额 → 支持配额（Quota）作为计量单位。

8.2 模型定价

每个模型有独立的定价倍率（Model Ratio）：输入倍率按输入 Token 计费，输出倍率 = 输入倍率 × 输出倍数。计算公式：

消耗配额 = 输入 Token 数 × 输入倍率 + 输出 Token 数 × 输出倍率
扣费金额（美元） = 消耗配额 ÷ 500,000
输入倍率 = 厂商官方最新输入价（美元 / 100 万 Token）÷ 2 × 1.1   ← 官方价 +10%

在售模型示例（价格为我方售价，即官方最新价 +10%）：

8.3 缓存优惠

部分模型对命中缓存的输入 Token 提供折扣费率（缓存读取倍率低于输入倍率），具体以模型广场展示的价格为准。

8.4 订阅计划

Ulnvault 提供 7 档订阅计划（月度自动续费，可在「订阅」页面随时取消）：

计划均包含月度配额、UAP Agent 实例数、资源限制（CPU/内存）与流量限额，具体以「订阅」页面为准。

8.5 安全注意事项

• API Key 泄漏可能导致配额盗用，请妥善保管
• 建议设置令牌限额和 IP 白名单增强安全性
• 账户余额不足时 API 调用将被拒绝
• 订阅计划按月自动续费，请及时关注账户状态

9. 附录

9.1 API 端点汇总

9.2 错误码参考

9.3 联系方式

如需技术支持或帮助：

• 📧 邮箱：contact@ulnit.com
• 📖 文档：https://docs.ulnit.com