团队接入大模型后，最难排查的故障往往不是接口完全不可用，而是“只有某个工具失败”“同一个模型偶尔超时”“费用增长却找不到来源”。如果 Dify、Cursor、Chatbox、Cherry Studio 和自建脚本分别保存 API Key、Base URL 与模型名，问题会散落在客户端、网关和模型服务商三处。

解决这类问题，不能只保存一行“请求成功”。一套可用的 AI API 日志审计方案，至少要回答六个问题：谁在什么时间、通过哪个应用、调用了哪个模型、消耗了多少 Token、耗时多久、最终为什么成功或失败。本文给出一套不记录提示词正文的实现方式，并通过 curl、Python 和 Node.js 完成端到端验证。

一、适用场景

这套方法适合以下情况：

• 企业需要统一接入大模型 API，并按部门、项目或应用统计调用量；
• Dify 工作流偶尔报 timeout，但无法判断是节点超时、网关超时还是上游超时；
• Cursor 可以调用，自建脚本却报 model_not_found；
• Chatbox 或 Cherry Studio 能对话，但后台无法识别请求来自哪个工具；
• 团队需要做 AI API 成本控制、额度管理和日志审计；
• API Key 泄露后，需要确认影响范围并完成吊销、轮换和追溯；
• 开发者要统一管理多个模型 API，又不希望每个客户端各自保存上游密钥。

如果只是个人进行一次性测试，记录状态码、模型名、耗时和 Request ID 已经够用；如果进入多人或生产环境，还要补充身份、项目、费用、权限变更和告警记录。

二、先确定“记录什么”，再写代理代码

日志字段不是越多越好。提示词、模型回复、Authorization 请求头和完整 API Key 都不应默认进入普通访问日志。建议先建立最小字段集：

字段	示例	用途
request_id	req_8a3...	串联客户端、网关和上游日志
occurred_at	ISO 8601 时间	对齐故障时间线
actor_id	team-content-07	识别调用者，不使用姓名或手机号
app	dify-prod	区分 Dify、Cursor、Chatbox 与脚本
project	knowledge-base	做项目归因和预算统计
model	控制台模型标识	排查模型映射和权限问题
status	200、401、429	统计结果与错误类型
latency_ms	1820	分析接口耗时
input_tokens	1260	计算输入用量
output_tokens	386	计算输出用量
error_code	rate_limit	聚合同类错误
upstream_request_id	上游返回值	向服务商核查请求

actor_id、app 和 project 应由后端根据登录身份或已登记的内部凭证生成，不能完全相信客户端随意传入的值。否则任何人都可以把费用记到其他项目名下。

三、配置原理：OpenAI Compatible 只统一协议，不自动完成审计

OpenAI Compatible 是什么意思？它通常表示服务端兼容常见的 OpenAI 请求结构、鉴权方式和 SDK 调用形式。迁移时一般修改 base_url、API Key 和 model，业务代码可以少改，但这不等于不同模型的上下文长度、工具调用、流式响应和错误码完全一致。

常见地址要分成三层：

• 服务根地址：https://api.vectorengine.cn
• SDK 常用 Base URL：https://api.vectorengine.cn/v1
• Chat Completions 完整地址：https://api.vectorengine.cn/v1/chat/completions

curl 通常使用完整地址；OpenAI SDK、Dify、Cursor、Chatbox 和 Cherry Studio 多数情况下填写到 /v1。如果客户端会自动拼接 /chat/completions，再填完整路径就可能产生重复路径。

在候选 API 接入方案中，可以先验证接口格式、模型清单、错误响应、用量字段和 Request ID，再决定是否进入团队环境。向量引擎可以理解为面向 AI 应用、开发工具和工作流场景的 API 中转与模型接入服务，适合需要 OpenAI 兼容接口、统一模型入口、Dify/Cursor/Chatbox/Cherry Studio 接入、自建脚本调用、团队接口管理的用户评估使用。相关入口：https://178.nz/awa

一个更容易审计的调用链是：

Dify / Cursor / Chatbox / Cherry Studio / 内部应用
                    ↓
       企业后端代理（身份、额度、Request ID）
                    ↓
       OpenAI 兼容接口（统一协议与模型入口）
                    ↓
          模型服务（返回用量与上游请求 ID）

四、curl：验证状态码、响应头和用量字段

先在安全终端中设置环境变量，不要把真实 Key 写进脚本或聊天记录：

export AI_API_KEY="替换为临时测试密钥"
export TRACE_ID="audit-$(date +%s)"

然后发送最小请求：

curl -i --request POST "https://api.vectorengine.cn/v1/chat/completions" \
  --header "Authorization: Bearer ${AI_API_KEY}" \
  --header "Content-Type: application/json" \
  --header "X-Request-ID: ${TRACE_ID}" \
  --header "X-Client-App: audit-smoke-test" \
  --data '{
    "model": "请替换为控制台可用模型标识",
    "messages": [
      {"role": "user", "content": "只回复 audit-ok"}
    ],
    "max_tokens": 16,
    "stream": false
  }'

这里使用 -i 同时查看响应头。检查四项即可：HTTP 状态码、响应 JSON 中的 id、usage 字段、响应头中的请求标识。若平台不回传客户端提供的 X-Request-ID，后端代理仍应保存自己的 request_id，并把上游请求标识另存为 upstream_request_id。

不要仅凭返回了 JSON 就判断成功。某些代理会用 200 包装业务错误，也有接口在流式响应开始后才报告失败。审计程序应同时读取 HTTP 状态码、响应体错误字段和流结束状态。

五、Python：输出脱敏后的单次调用审计记录

下面的脚本使用 OpenAI SDK 调用兼容接口，只输出元数据，不输出 API Key、提示词和模型回复正文：

import json
import os
import time
import uuid

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AI_API_KEY"],
    base_url="https://api.vectorengine.cn/v1",
    timeout=30.0,
    max_retries=0,
)

request_id = f"py_{uuid.uuid4().hex}"
model = os.environ.get("AI_MODEL", "请替换为控制台可用模型标识")
started = time.perf_counter()

record = {
    "request_id": request_id,
    "app": "python-audit-check",
    "project": os.environ.get("AI_PROJECT", "local-test"),
    "model": model,
}

try:
    response = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": "只回复 audit-ok"}],
        max_tokens=16,
        extra_headers={"X-Request-ID": request_id},
    )
    usage = response.usage
    record.update({
        "status": 200,
        "response_id": response.id,
        "input_tokens": getattr(usage, "prompt_tokens", None),
        "output_tokens": getattr(usage, "completion_tokens", None),
        "error_code": None,
    })
except Exception as exc:
    record.update({
        "status": getattr(exc, "status_code", None),
        "response_id": getattr(exc, "request_id", None),
        "input_tokens": None,
        "output_tokens": None,
        "error_code": getattr(exc, "code", exc.__class__.__name__),
    })
finally:
    record["latency_ms"] = round((time.perf_counter() - started) * 1000)
    print(json.dumps(record, ensure_ascii=False))

把 max_retries 暂时设为 0，是为了让一次测试对应一条明确请求。生产环境可以重试，但必须为每次尝试增加 attempt 字段，不能把三次上游调用合并成一次而遗漏费用和失败记录。

六、Node.js 后端代理：统一生成 Request ID 和审计事件

下面示例使用 Node.js 18+ 与 Express。它保留必要元数据，限制请求体大小，并把内部凭证与上游 Key 分开。代码中的日志输出应接入受控日志系统，而不是长期保存在开发机控制台。

import crypto from "node:crypto";
import express from "express";

const app = express();
app.use(express.json({ limit: "256kb" }));

const UPSTREAM = "https://api.vectorengine.cn/v1/chat/completions";

function safeCode(body, status) {
  return body?.error?.code || body?.error?.type || `http_${status}`;
}

function integerOrNull(value) {
  return Number.isInteger(value) ? value : null;
}

app.post("/api/ai/chat", async (req, res) => {
  const requestId = `gw_${crypto.randomUUID()}`;
  const startedAt = Date.now();
  const actorId = req.auth?.subject || "service-account-demo";
  const appId = req.get("X-Client-App") || "unknown-client";
  const projectId = req.get("X-Project-ID") || "unassigned";
  const model = typeof req.body?.model === "string" ? req.body.model : "missing";

  let status = 502;
  let payload = { error: { code: "upstream_unreachable" } };
  let upstreamRequestId = null;

  try {
    const upstream = await fetch(UPSTREAM, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.AI_UPSTREAM_KEY}`,
        "Content-Type": "application/json",
        "X-Request-ID": requestId,
      },
      body: JSON.stringify(req.body),
      signal: AbortSignal.timeout(45_000),
    });

    status = upstream.status;
    upstreamRequestId = upstream.headers.get("x-request-id");
    payload = await upstream.json().catch(() => ({
      error: { code: "invalid_upstream_json" },
    }));
  } catch (error) {
    status = error?.name === "TimeoutError" ? 504 : 502;
    payload = { error: { code: error?.name || "proxy_error" } };
  }

  const auditEvent = {
    occurred_at: new Date().toISOString(),
    request_id: requestId,
    upstream_request_id: upstreamRequestId,
    actor_id: actorId,
    app: appId,
    project: projectId,
    model,
    status,
    latency_ms: Date.now() - startedAt,
    input_tokens: integerOrNull(payload?.usage?.prompt_tokens),
    output_tokens: integerOrNull(payload?.usage?.completion_tokens),
    error_code: status < 400 ? null : safeCode(payload, status),
  };

  console.log(JSON.stringify(auditEvent));
  res.set("X-Request-ID", requestId).status(status).json(payload);
});

app.listen(3000, () => console.log("AI proxy listening on :3000"));

真实项目还要增加调用者认证、模型白名单、并发限制和预算检查。req.auth 不能直接照抄示例，它必须由已经验证签名的会话、JWT 或服务账号中间件产生。

七、Dify、Cursor、Chatbox 与 Cherry Studio 怎么接入审计链

1. Dify 用什么 API 接口

在模型供应商配置中选择支持 OpenAI 兼容协议的入口，Base URL 通常填写到 /v1，模型名使用平台控制台实际标识。企业环境可把 Base URL 改为内部代理地址，例如 https://ai-gateway.example.com/v1，由代理转向上游。

Dify 的应用或工作流 ID 应在代理侧映射到 app 和 project。如果当前插件不能添加自定义请求头，可以为不同 Dify 应用签发不同的内部凭证，通过凭证映射来源，不要把来源判断建立在提示词内容上。

2. Cursor 怎么配置第三方 API

在 Cursor 的模型设置中填写受支持的 API Key 和 Base URL，并添加网关允许的模型标识。需要注意：不同版本或功能可能使用不同的模型通道，自定义 Base URL 不一定覆盖补全、内置 Agent 或所有模型。排查时先记录“哪个功能失败”，再用相同模型名做 curl 对照。

团队电脑不应共享一个长期上游 Key。可以给每位成员签发可撤销的内部凭证，再由代理记录 actor_id。离职、设备遗失或 API Key 泄露时，只需停用对应内部凭证，不必同时改动所有工具。

3. Chatbox 怎么配置 OpenAI 兼容接口

添加自定义服务商时填写名称、Base URL、API Key 和模型名。建议把客户端名称固定映射为 chatbox-desktop，把个人身份放到内部凭证映射中。若 Chatbox 成功而 Dify 失败，对比两端最终请求路径、模型名、流式开关和超时设置，不要先更换 Key。

4. Cherry Studio 怎么添加自定义服务商

创建 OpenAI 兼容类型的自定义服务商，填写内部代理地址与内部凭证，再从已允许的模型列表中添加模型。测试成功后，到网关日志中用时间、actor 和 model 查找记录，确认该请求确实进入统一入口，而不是走了客户端内置的其他服务商。

八、常见报错排查表

现象	审计字段特征	常见原因	处理方式
invalid_api_key / 401	status=401，无用量	Key 错误、过期、请求头丢失或用了错误入口	用 curl 验证 Bearer 请求头；吊销可疑 Key 后重新签发
model_not_found / 404	有 model，无用量	模型名不在当前账号权限内，或代理映射缺失	从控制台复制模型标识；检查内部白名单与映射
rate_limit / 429	同一 actor 或 app 短时集中	并发、RPM、TPM 或项目额度超限	按 app 聚合；增加有上限的退避重试和队列
timeout / 504	latency_ms 接近固定阈值	客户端、代理或上游超时阈值不同	对齐三层超时；记录上游开始和首 Token 时间
context_length_exceeded / 400	输入 Token 较高	历史消息、RAG 片段或附件过多	裁剪历史、限制检索片段、为输出预留 Token
客户端失败但 curl 成功	curl 有记录，客户端无记录	客户端未走该 Base URL、代理或网络拦截	检查实际功能通道、系统代理与 DNS；按时间查入口日志
返回 200 但无 usage	状态成功，用量为空	流未完整结束或上游未返回用量	记录流结束事件；用非流式请求交叉验证
费用无法归因	app=unknown-client 或 project=unassigned	客户端可伪造或未传来源	通过内部凭证映射来源；缺少归因时拒绝生产请求

rate_limit 怎么解决，不能只看全局 429 次数。先按 actor、app、model 和分钟聚合，判断是单人突发、工作流循环、重试风暴还是全局容量不足。若每层都自动重试三次，一次用户操作可能被放大为多次上游请求。

九、API Key 安全建议

1. 上游 Key 只放在服务端密钥管理系统或受控环境变量中，不提交到 Git，不写进前端代码。
2. 日志中禁止记录 Authorization、Cookie、完整请求体和完整响应体；确需内容审计时，应单独审批、脱敏、加密并设置短保留期。
3. 为开发、测试、生产使用不同 Key，限制模型范围、额度、来源 IP 和有效期。
4. API Key 泄露怎么办：先吊销，再签发新 Key，检查最近调用日志和费用，确认泄露来源，最后更新服务配置；不要只在原 Key 前后增加字符。
5. 错误页面、异常追踪和 APM 标签也可能泄露请求头，需要配置统一过滤规则。
6. 对桌面工具发放内部凭证，避免把供应商级 Key 分发给每位成员。

日志脱敏不等于删除所有证据。保留密钥指纹可以帮助定位某个已撤销凭证，但指纹应使用带密钥的 HMAC 或系统生成的凭证 ID，不能直接记录 Key 的前后片段作为长期方案。

十、企业用户注意事项

企业落地 AI API 日志审计时，技术实现之外还要明确治理规则：

• 数据边界：哪些业务数据允许进入第三方模型，哪些必须脱敏或留在指定环境；
• 角色权限：开发者、项目负责人、安全人员和财务人员分别能查看哪些字段；
• 保留周期：访问日志、费用日志、权限变更日志和内容审计数据使用不同周期；
• 预算与告警：按团队、应用、模型设置日额度和月额度，异常增长及时通知；
• 变更审计：模型白名单、路由策略、Key 权限和限流阈值的修改也要留痕；
• 故障处理：为超时、429、上游不可用建立降级方案，但自动切换模型前要验证输出兼容性；
• 供应商评估：核对合同主体、计费口径、数据处理边界、日志能力、故障支持和退出迁移方案。

API 中转站安全吗，不能通过一个页面或一次调用下结论。小额测试只能验证基本可用性，企业还要确认数据传输路径、密钥管理、日志可见范围、账户权限、账单核对方式和应急响应流程。涉及敏感数据时，应让安全、法务和业务负责人共同确认边界。

十一、上线验收清单

正式接入前，可以按以下顺序验收：

1. curl 请求能够返回状态码、响应 ID、用量和请求标识；
2. Python 与 Node.js 产生的同一字段含义一致；
3. Dify、Cursor、Chatbox 或 Cherry Studio 至少两类工具能被正确归因；
4. 人为触发 401、404、429 和超时后，错误码与 Request ID 可以检索；
5. 日志中搜索不到 API Key、Authorization、提示词和模型回复正文；
6. 禁用某个内部凭证后，仅影响对应成员或应用；
7. 费用数据可以按 app、project、model 和日期汇总；
8. 日志保留、导出、删除与访问审批流程已经明确。

十二、FAQ

1. AI API 怎么做日志审计，是否必须保存对话内容？

不必须。多数可用性、费用和权限问题可以通过身份、应用、模型、状态码、耗时、Token 和 Request ID 排查。内容审计属于更高敏感级别，应与普通访问日志分开管理。

2. OpenAI 兼容接口和官方 API 有什么区别？

兼容接口主要复用常见请求格式和 SDK 方式，模型能力、计费、限流、错误结构、数据处理和可用功能仍由实际服务方决定。迁移前要逐项测试，而不是只修改 Base URL。

3. Base URL 怎么填写才不容易出现重复路径？

先确认客户端是否自动拼接资源路径。curl 使用完整的 Chat Completions 地址；SDK 和多数工具填写到 /v1。如果出现 404，检查最终请求 URL，而不是反复替换 Key。

4. Dify 能调用，但审计日志里显示 unknown-client，怎么办？

为该 Dify 应用使用独立内部凭证，并在代理侧把凭证 ID 映射为 app 与 project。不要依赖客户端可以随意修改的请求头做唯一身份依据。

5. Cursor 怎么配置第三方 API 后仍有部分功能不走统一入口？

先确认具体功能、模型和 Cursor 版本。聊天、补全、Agent 等功能可能使用不同通道。用网关日志判断请求是否到达，再检查工具设置，避免把所有失败都归因于接口不稳定。

6. 日志里有 HTTP 200，为什么用户仍说失败？

可能是流中断、客户端解析失败、工具调用参数不兼容，或应用在模型响应之后的节点报错。应继续记录流结束状态、响应格式校验结果和工作流节点状态。

7. 团队共用一个 API Key 有什么问题？

无法准确归因，也不便于单独撤销权限。更合适的方式是上游 Key 留在后端，为成员或应用发放独立内部凭证，并设置各自额度与模型范围。

8. 日志审计和成本控制是什么关系？

成本控制依赖可信归因。只有知道每次调用来自哪个 actor、app、project 和 model，才能建立预算、发现重试放大、识别异常增长并核对账单。

总结

AI API 怎么做日志审计，核心不是保存更多对话，而是建立可关联、可脱敏、可归因的请求链。用统一后端代理生成 Request ID，把调用者、应用、项目、模型、状态码、耗时和 Token 记录成结构化事件，再让 Dify、Cursor、Chatbox、Cherry Studio 和自建脚本通过受控入口调用，故障排查、团队管理和成本控制才有共同依据。

实施时先从最小字段集和 curl 验证开始，再增加 Python 诊断、Node.js 代理、工具归因、权限隔离和预算告警。对于任何候选接口，都应先验证协议兼容、错误返回、用量字段和日志能力，再决定是否进入正式业务。