Skip to content

Commit 627579b

Browse files
authored
fix(deepseek): read documented top-level prompt-cache counters (#2252)
What: - Add src/api/transform/chat-usage-normalization.ts, a shared normalizer that resolves OpenAI-shaped chat-completions usage into { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens }. - DeepSeekHandler.processUsageMetrics now uses the normalizer instead of reading usage.prompt_tokens_details.cache_miss_tokens directly. - Rewrite the deepseek spec fixtures to DeepSeek's documented wire shape and add top-level-only, nested-only-legacy, and both-shapes-present cases. Why: DeepSeek's OpenAPI marks prompt_cache_hit_tokens and prompt_cache_miss_tokens as required top-level members and declares only cached_tokens inside prompt_tokens_details. The nested cache_miss_tokens field the provider read does not exist, so cacheWriteTokens was permanently undefined. DeepSeek catalog entries set inputPrice: 0 (inputs are priced as cache read/write only), so calculateApiCostOpenAI priced every cache-miss input token at zero: a permanent, near-total under-report of DeepSeek input cost. The old spec hid this by mocking the non-existent nested shape and asserting cacheWriteTokens from it, so the suite was green because it mocked the bug. Read priority is per-field with no summing, because the two shapes describe the same quantities: - cacheWriteTokens: prompt_cache_miss_tokens, then nested cache_miss_tokens (legacy fallback), then nested cache_write_tokens. - cacheReadTokens: nested cached_tokens, then prompt_cache_hit_tokens, then cache_read_input_tokens. Impact: DeepSeek input cost is now reported instead of collapsing to ~$0 for cache-miss tokens. The helper is generic over OpenAI-shaped usage so the family-wide provider rewiring can adopt it without a second implementation. No behavior change for providers that do not use the helper. Refs: https://api-docs.deepseek.com/api/create-chat-completion https://api-docs.deepseek.com/api/create-completion
1 parent 07007b4 commit 627579b

4 files changed

Lines changed: 323 additions & 27 deletions

File tree

‎src/api/providers/__tests__/deepseek.spec.ts‎

Lines changed: 66 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,10 @@ vi.mock("openai", () => {
2727
completion_tokens: 5,
2828
total_tokens: 15,
2929
prompt_tokens_details: {
30-
cache_miss_tokens: 8,
3130
cached_tokens: 2,
3231
},
32+
prompt_cache_hit_tokens: 2,
33+
prompt_cache_miss_tokens: 8,
3334
},
3435
}
3536
}
@@ -111,9 +112,10 @@ vi.mock("openai", () => {
111112
completion_tokens: 5,
112113
total_tokens: 15,
113114
prompt_tokens_details: {
114-
cache_miss_tokens: 8,
115115
cached_tokens: 2,
116116
},
117+
prompt_cache_hit_tokens: 2,
118+
prompt_cache_miss_tokens: 8,
117119
},
118120
})
119121

@@ -517,52 +519,93 @@ describe("DeepSeekHandler", () => {
517519
})
518520

519521
describe("processUsageMetrics", () => {
520-
it("should correctly process usage metrics including cache information", () => {
521-
// We need to access the protected method, so we'll create a test subclass
522-
class TestDeepSeekHandler extends DeepSeekHandler {
523-
public testProcessUsageMetrics(usage: any) {
524-
return this.processUsageMetrics(usage)
525-
}
522+
class TestDeepSeekHandler extends DeepSeekHandler {
523+
public testProcessUsageMetrics(usage: any) {
524+
return this.processUsageMetrics(usage)
526525
}
526+
}
527527

528-
const testHandler = new TestDeepSeekHandler(mockOptions)
528+
// mockOptions is assigned in beforeEach, so the handler must be built
529+
// per test rather than at describe-collection time.
530+
const processUsage = (usage: any) => new TestDeepSeekHandler(mockOptions).testProcessUsageMetrics(usage)
531+
532+
// DeepSeek's OpenAPI marks prompt_cache_hit_tokens and
533+
// prompt_cache_miss_tokens as required top-level members, and declares
534+
// only cached_tokens inside prompt_tokens_details. This is the vendor's
535+
// own documented example response.
536+
// https://api-docs.deepseek.com/api/create-chat-completion
537+
it("reads the documented top-level cache counters", () => {
538+
const result = processUsage({
539+
prompt_tokens: 7,
540+
completion_tokens: 11,
541+
total_tokens: 18,
542+
prompt_tokens_details: { cached_tokens: 0 },
543+
prompt_cache_hit_tokens: 0,
544+
prompt_cache_miss_tokens: 7,
545+
})
529546

530-
const usage = {
547+
expect(result.type).toBe("usage")
548+
expect(result.inputTokens).toBe(7)
549+
expect(result.outputTokens).toBe(11)
550+
expect(result.cacheReadTokens).toBe(0)
551+
expect(result.cacheWriteTokens).toBe(7)
552+
})
553+
554+
it("reads top-level cache counters when prompt_tokens_details is absent", () => {
555+
const result = processUsage({
556+
prompt_tokens: 100,
557+
completion_tokens: 50,
558+
total_tokens: 150,
559+
prompt_cache_hit_tokens: 20,
560+
prompt_cache_miss_tokens: 80,
561+
})
562+
563+
expect(result.inputTokens).toBe(100)
564+
expect(result.outputTokens).toBe(50)
565+
expect(result.cacheWriteTokens).toBe(80)
566+
expect(result.cacheReadTokens).toBe(20)
567+
})
568+
569+
it("falls back to the nested cache counters for legacy shapes", () => {
570+
const result = processUsage({
531571
prompt_tokens: 100,
532572
completion_tokens: 50,
533573
total_tokens: 150,
534574
prompt_tokens_details: {
535575
cache_miss_tokens: 80,
536576
cached_tokens: 20,
537577
},
538-
}
539-
540-
const result = testHandler.testProcessUsageMetrics(usage)
578+
})
541579

542-
expect(result.type).toBe("usage")
543580
expect(result.inputTokens).toBe(100)
544581
expect(result.outputTokens).toBe(50)
545582
expect(result.cacheWriteTokens).toBe(80)
546583
expect(result.cacheReadTokens).toBe(20)
547584
})
548585

549-
it("should handle missing cache metrics gracefully", () => {
550-
class TestDeepSeekHandler extends DeepSeekHandler {
551-
public testProcessUsageMetrics(usage: any) {
552-
return this.processUsageMetrics(usage)
553-
}
554-
}
586+
it("does not double-count when both shapes are present", () => {
587+
const result = processUsage({
588+
prompt_tokens: 100,
589+
completion_tokens: 50,
590+
total_tokens: 150,
591+
prompt_tokens_details: { cached_tokens: 20, cache_miss_tokens: 80 },
592+
prompt_cache_hit_tokens: 20,
593+
prompt_cache_miss_tokens: 80,
594+
})
555595

556-
const testHandler = new TestDeepSeekHandler(mockOptions)
596+
expect(result.cacheWriteTokens).toBe(80)
597+
expect(result.cacheReadTokens).toBe(20)
598+
})
557599

600+
it("should handle missing cache metrics gracefully", () => {
558601
const usage = {
559602
prompt_tokens: 100,
560603
completion_tokens: 50,
561604
total_tokens: 150,
562-
// No prompt_tokens_details
605+
// No prompt_tokens_details and no top-level cache counters
563606
}
564607

565-
const result = testHandler.testProcessUsageMetrics(usage)
608+
const result = processUsage(usage)
566609

567610
expect(result.type).toBe("usage")
568611
expect(result.inputTokens).toBe(100)

‎src/api/providers/deepseek.ts‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ import type { ApiHandlerOptions, GetModelsOptions } from "../../shared/api"
1515
import { ApiStream, ApiStreamUsageChunk } from "../transform/stream"
1616
import { getModelParams } from "../transform/model-params"
1717
import { convertToR1Format } from "../transform/r1-format"
18+
import { normalizeChatUsage } from "../transform/chat-usage-normalization"
1819

1920
import { OpenAiHandler } from "./openai"
2021
import { NOT_PROVIDED } from "./constants"
@@ -227,13 +228,20 @@ export class DeepSeekHandler extends OpenAiHandler {
227228
}
228229

229230
// Override to handle DeepSeek's usage metrics, including caching.
231+
// DeepSeek reports cache counters in two shapes that describe the same
232+
// quantities: top-level `prompt_cache_hit_tokens` / `prompt_cache_miss_tokens`
233+
// and nested `prompt_tokens_details.cached_tokens`. The normalizer resolves
234+
// one value per field and never sums the shapes.
235+
// https://api-docs.deepseek.com/api/create-chat-completion
230236
protected override processUsageMetrics(usage: any, _modelInfo?: any): ApiStreamUsageChunk {
237+
const normalized = normalizeChatUsage(usage)
238+
231239
return {
232240
type: "usage",
233-
inputTokens: usage?.prompt_tokens || 0,
234-
outputTokens: usage?.completion_tokens || 0,
235-
cacheWriteTokens: usage?.prompt_tokens_details?.cache_miss_tokens,
236-
cacheReadTokens: usage?.prompt_tokens_details?.cached_tokens,
241+
inputTokens: normalized?.inputTokens ?? 0,
242+
outputTokens: normalized?.outputTokens ?? 0,
243+
cacheWriteTokens: normalized?.cacheWriteTokens,
244+
cacheReadTokens: normalized?.cacheReadTokens,
237245
}
238246
}
239247
}
Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
// npx vitest run api/transform/__tests__/chat-usage-normalization.spec.ts
2+
3+
import { normalizeChatUsage } from "../chat-usage-normalization"
4+
5+
// Documented DeepSeek usage block, copied from the vendor's OpenAPI example.
6+
// https://api-docs.deepseek.com/api/create-chat-completion
7+
const documentedDeepSeekUsage = {
8+
prompt_tokens: 7,
9+
completion_tokens: 11,
10+
total_tokens: 18,
11+
prompt_tokens_details: { cached_tokens: 0 },
12+
prompt_cache_hit_tokens: 0,
13+
prompt_cache_miss_tokens: 7,
14+
}
15+
16+
describe("normalizeChatUsage", () => {
17+
it("returns undefined when the provider sent no usage object", () => {
18+
expect(normalizeChatUsage(undefined)).toBeUndefined()
19+
expect(normalizeChatUsage(null)).toBeUndefined()
20+
})
21+
22+
it("returns undefined for a truthy non-object usage value", () => {
23+
// A malformed proxy can send a scalar where the usage object belongs.
24+
expect(normalizeChatUsage("usage" as unknown as Record<string, unknown>)).toBeUndefined()
25+
expect(normalizeChatUsage(0 as unknown as Record<string, unknown>)).toBeUndefined()
26+
})
27+
28+
it("reads the documented DeepSeek top-level shape", () => {
29+
expect(normalizeChatUsage(documentedDeepSeekUsage)).toEqual({
30+
inputTokens: 7,
31+
outputTokens: 11,
32+
cacheReadTokens: 0,
33+
cacheWriteTokens: 7,
34+
})
35+
})
36+
37+
it("reads a top-level-only usage object with no nested details", () => {
38+
expect(
39+
normalizeChatUsage({
40+
prompt_tokens: 120,
41+
completion_tokens: 30,
42+
prompt_cache_hit_tokens: 100,
43+
prompt_cache_miss_tokens: 20,
44+
}),
45+
).toEqual({ inputTokens: 120, outputTokens: 30, cacheReadTokens: 100, cacheWriteTokens: 20 })
46+
})
47+
48+
it("reads the nested-only shape used by OpenAI and by legacy DeepSeek fixtures", () => {
49+
expect(
50+
normalizeChatUsage({
51+
prompt_tokens: 100,
52+
completion_tokens: 50,
53+
prompt_tokens_details: { cached_tokens: 20, cache_miss_tokens: 80 },
54+
}),
55+
).toEqual({ inputTokens: 100, outputTokens: 50, cacheReadTokens: 20, cacheWriteTokens: 80 })
56+
})
57+
58+
it("does not add the nested and top-level shapes together when both are present", () => {
59+
// Both shapes describe the same 100 reads / 20 writes. Summing would
60+
// report 200 / 40 and double the billed cache tokens.
61+
const normalized = normalizeChatUsage({
62+
prompt_tokens: 120,
63+
completion_tokens: 30,
64+
prompt_tokens_details: { cached_tokens: 100, cache_miss_tokens: 20 },
65+
prompt_cache_hit_tokens: 100,
66+
prompt_cache_miss_tokens: 20,
67+
})
68+
69+
expect(normalized?.cacheReadTokens).toBe(100)
70+
expect(normalized?.cacheWriteTokens).toBe(20)
71+
})
72+
73+
it("prefers the nested cached_tokens over the top-level hit counter for reads", () => {
74+
expect(
75+
normalizeChatUsage({
76+
prompt_tokens: 120,
77+
prompt_tokens_details: { cached_tokens: 100 },
78+
prompt_cache_hit_tokens: 90,
79+
})?.cacheReadTokens,
80+
).toBe(100)
81+
})
82+
83+
it("prefers the top-level miss counter over the nested one for writes", () => {
84+
expect(
85+
normalizeChatUsage({
86+
prompt_tokens: 120,
87+
prompt_tokens_details: { cache_miss_tokens: 20 },
88+
prompt_cache_miss_tokens: 30,
89+
})?.cacheWriteTokens,
90+
).toBe(30)
91+
})
92+
93+
it("falls through a malformed alias to the next one", () => {
94+
expect(
95+
normalizeChatUsage({
96+
prompt_tokens: 120,
97+
prompt_cache_miss_tokens: "30",
98+
prompt_tokens_details: { cache_miss_tokens: 20 },
99+
})?.cacheWriteTokens,
100+
).toBe(20)
101+
})
102+
103+
it("leaves cache counters undefined when the provider reports none", () => {
104+
const normalized = normalizeChatUsage({ prompt_tokens: 100, completion_tokens: 50, total_tokens: 150 })
105+
106+
expect(normalized).toEqual({ inputTokens: 100, outputTokens: 50 })
107+
expect(normalized).not.toHaveProperty("cacheReadTokens")
108+
expect(normalized).not.toHaveProperty("cacheWriteTokens")
109+
})
110+
111+
it("rejects negative and fractional token counts", () => {
112+
expect(
113+
normalizeChatUsage({
114+
prompt_tokens: 120,
115+
prompt_cache_hit_tokens: -1,
116+
prompt_cache_miss_tokens: 1.5,
117+
}),
118+
).toEqual({ inputTokens: 120, outputTokens: 0 })
119+
})
120+
121+
it("defaults missing prompt and completion tokens to zero", () => {
122+
expect(normalizeChatUsage({})).toEqual({ inputTokens: 0, outputTokens: 0 })
123+
})
124+
})

0 commit comments

Comments
 (0)