稽核日誌

稽核日誌記錄你的 API 所有操作歷史——每一次 Chat 請求、每一次記憶新增、每一次文件上傳，都留有可查詢的記錄。

適合用在： 計費對帳、使用量監控、安全稽核、問題排查。

記錄的內容

每條稽核日誌包含：

欄位	說明
action	操作類型（例如 gateway.chat、memory.write）
created_at	操作時間
model	使用的 AI 模型（Gateway 請求）
credits_consumed	消耗的 Credits（RAG / Memory）
balance_consumed_usd	消耗的 USD 餘額（LLM Token）
metadata	你在請求中帶的自訂標記
audit_id	唯一識別碼，對應每次 API 呼叫

常見操作類型

操作	說明
gateway.chat	Chat Completions 請求
gateway.embedding	Embeddings 請求
gateway.rerank	Rerank 請求
rag.query	直接查詢知識庫
memory.read	讀取記憶
memory.write	新增/修改/刪除記憶
memory.search	語義搜尋記憶
memory.extract	LLM 萃取記憶
document.read	讀取文件
document.write	管理文件

查詢稽核日誌

Node.js

import { Vecstruct } from '@vecstruct/sdk';

const client = new Vecstruct({ apiKey: process.env.VECSTRUCT_API_KEY });

const logs = await client.audit.list({
  start_time: '2026-05-01T00:00:00Z',
  end_time: '2026-05-08T00:00:00Z',
  page: 1,
  page_size: 20,
});

console.log(`共 ${logs.pagination.total} 條記錄`);
for (const log of logs.items) {
  console.log(`${log.created_at} | ${log.action} | $${log.balance_consumed_usd?.toFixed(6) ?? '0'}`);
}

Python

from vecstruct import AsyncVecstruct

async with AsyncVecstruct() as client:
    logs = await client.audit.logs.list(
        start_time="2026-05-01T00:00:00Z",
        end_time="2026-05-08T00:00:00Z",
        page=1,
        page_size=20,
    )
    for log in logs["items"]:
        print(f"{log['created_at']} | {log['action']}")

Go

import vecstruct "github.com/vecstruct/vecstruct-sdk-go"

logs, err := client.ListAuditLogs(ctx, &vecstruct.ListAuditLogsOptions{
    StartTime: "2026-05-01T00:00:00Z",
    EndTime:   "2026-05-08T00:00:00Z",
    Page:      1,
    PageSize:  20,
})
if err != nil {
    log.Fatal(err)
}
for _, entry := range logs.Logs {
    fmt.Printf("%s | %s\n", entry.CreatedAt, entry.Action)
}

按操作類型篩選

Node.js

const chatLogs = await client.audit.list({
  action: 'gateway.chat',
  start_time: '2026-05-01T00:00:00Z',
  end_time: '2026-05-08T00:00:00Z',
});

Python

logs = await client.audit.logs.list(
    action="gateway.chat",
    start_time="2026-05-01T00:00:00Z",
    end_time="2026-05-08T00:00:00Z",
)

Go

logs, err := client.ListAuditLogs(ctx, &vecstruct.ListAuditLogsOptions{
    Action:    "gateway.chat",
    StartTime: "2026-05-01T00:00:00Z",
    EndTime:   "2026-05-08T00:00:00Z",
})

查看單條記錄詳情

Node.js

const detail = await client.audit.retrieve('audit-uuid');
console.log('使用模型:', detail.model);
console.log('Token 用量:', detail.usage);
console.log('自訂 Metadata:', detail.metadata);

Python

detail = await client.audit.logs.get("audit-uuid")
print("使用模型:", detail["model"])
print("Token 用量:", detail["usage"])

Go

detail, err := client.GetAuditLog(ctx, "audit-uuid")
if err != nil {
    log.Fatal(err)
}
fmt.Println("使用模型:", detail.Model)
fmt.Println("操作類型:", detail.Action)

匯出記錄

支援匯出為 CSV 或 JSON 格式，方便匯入 Excel 或其他分析工具：

Node.js

const job = await client.audit.export({
  format: 'csv',
  start_time: '2026-05-01T00:00:00Z',
  end_time: '2026-05-31T23:59:59Z',
});

console.log('匯出任務 ID:', job.export_id);

Python

job = await client.audit.logs.export(
    format="csv",
    start_time="2026-05-01T00:00:00Z",
    end_time="2026-05-31T23:59:59Z",
)
print("匯出任務 ID:", job["export_id"])

Go

job, err := client.ExportAuditLogs(ctx, vecstruct.ExportAuditLogsRequest{
    StartTime: "2026-05-01T00:00:00Z",
    EndTime:   "2026-05-31T23:59:59Z",
    Format:    vecstruct.ExportFormatCSV,
})
if err != nil {
    log.Fatal(err)
}
fmt.Println("匯出任務 ID:", job.ExportID)

---

自訂 Metadata 追蹤

在 Chat 請求中加入自訂的 metadata，可以關聯你自己系統的 ID（用戶 ID、工單 ID 等），方便之後查詢對帳：

Node.js

const reply = await client.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: [{ role: 'user', content: '...' }],
  vecstruct: {
    rag: true,
    metadata: {
      user_id: 'user-12345',        // 你系統的使用者 ID
      ticket_id: 'ticket-67890',    // 客服工單 ID
      department: 'customer_service',
    },
  },
});

Python

reply = await client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "..."}],
    vecstruct={
        "rag": True,
        "metadata": {
            "user_id": "user-12345",
            "ticket_id": "ticket-67890",
        },
    },
)

Go

ragOn := true
resp, err := client.CreateChatCompletion(ctx, vecstruct.ChatCompletionRequest{
    Model: "openai/gpt-4o",
    Messages: []vecstruct.ChatMessage{
        {Role: "user", Content: "..."},
    },
    Vecstruct: &vecstruct.VecstructParams{
        RAG: &ragOn,
        Metadata: map[string]any{
            "user_id":   "user-12345",
            "ticket_id": "ticket-67890",
        },
    },
})

---

保留期限

稽核日誌保留期限依方案而定：

方案	保留天數
Free	7 天
Basic	30 天
Pro	90 天
Business	365 天

---

注意事項

• 查詢稽核日誌需要 audit.read 權限
• 匯出稽核日誌需要 audit.export 權限（Pro+ 方案）
• 稽核日誌不可修改或刪除，超過保留期限後自動清除
• metadata 中的每個 key 只能是字母、數字、底線，值必須是字串、數字或布林值