Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions docs/development.md
Original file line number Diff line number Diff line change
Expand Up @@ -396,6 +396,7 @@ api 层的公开接口规则:
| `cascade`、`trajectory` | UUID 字符串 | 会话 ID 与轨迹 ID |
| `length` | 整数 | 最近一次请求在摘要链中的位置 |
| `digest` | 十六进制字符串 | 该位置的链摘要 |
| `chain` | 十六进制字符串数组,可省略 | 链首之后、该位置之前的全部链摘要,供回退匹配 |
| `answer` | 字符串,可省略 | 该次成功生成的回答指纹 |
| `times` | 整数数组 | 各条消息首次出现的 Unix 秒 |
| `prompt` | 对象,可省略 | 最近一次成功生成的提示规模 |
Expand All @@ -413,7 +414,7 @@ api 层的公开接口规则:

- `origins` 的键为签名 SHA-256 前 16 字节的小写十六进制,值为生成它的模型的 `modelProvider`(`MODEL_PROVIDER_GOOGLE`、`MODEL_PROVIDER_ANTHROPIC`、`MODEL_PROVIDER_OPENAI`)
- 会话记录写入时先写同目录临时文件(`.conversation-*`)再替换;启动时删除写入中断留下的临时文件并读入全部记录,任一文件无法解析时服务启动失败
- 写入时机:请求开始时(取得会话后、选择账户前)写 `length`、`digest`、`times` 与 `used`,`answer` 清空;`times` 先截到上一次的 `length` 再按当前时刻补齐本次多出的消息。生成正常结束后再写 `prompt`、`signatures`、`origins`,会话仍停在本次请求时写 `answer`
- 写入时机:请求开始时(取得会话后、选择账户前)写 `length`、`digest`、`chain`、`times` 与 `used`,`answer` 清空;`times` 先截到上一次的 `length`(回退时为从第 1 条消息起与本次相同的消息条数)再按当前时刻补齐本次多出的消息。生成正常结束后再写 `prompt`、`signatures`、`origins`,会话仍停在本次请求时写 `answer`
- 失败或取消的请求只有请求开始时的写入;之后原样重发时按协议参考「会话 ID」第 3 步匹配回同一会话,沿用已写的 `times`
- 摘要链:`digest(prev, data) = hex(SHA-256(prev + data))`,`prev` 为上一项的小写十六进制文本;`d0 = digest("", {"Session":<分区>,"System":<去掉计费行后的客户端系统提示>,"Tools":<规范工具>})`,`di = digest(d(i-1), 第 i 条规范消息的 JSON)`
- 回答指纹:`digest("", 正文 + NUL + 调用)`。正文为各非思考 part 的 `text` 相连后按 Go `strings.Fields` 切分、以单个空格相连;调用为各函数调用的“函数名 + 参数 JSON”以 NUL 相连,参数 JSON 先解析再编码,对象键按字典序
Expand Down Expand Up @@ -1624,7 +1625,7 @@ go vet ./...
| `balancer` | 按目录选账户、最久未选中者轮换、等待槽位、冷却、会话粘连、排除账户、目录合并 |
| `app` | 远程管理需要登录、验证链接、代理脱敏 |
| `requestdb` | 记录查询与详情、正文保留条数、过期清理、汇总与记录一致、日志查询、结果判定、上游错误读取、费用 |
| `service` | 流中错误原样返回、客户端取消后排空上游 |
| `service` | 流中错误原样返回、客户端取消后排空上游、原样重发与多出几条消息的续接归入原会话、改写已发消息与回退仍用原会话、第一条消息不同的请求新建会话、只有一条消息的请求成功后原样重发新建会话、回退到任意更早的消息仍用原会话、回退的相同部分更长时不被只含首条消息的会话取走 |
| `sqlitedb` | 打开已有库时保留记录、删除建表语句中没有的表与索引、转为增量收缩并交还空闲页 |
| `api` | 空消息过滤、Gemini 输出 part 与签名、`inlineData` 兼容、API key 匹配 |

Expand Down
9 changes: 5 additions & 4 deletions docs/protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -1352,9 +1352,10 @@ accept-encoding: gzip

1. 分区:API key 与客户端会话标识(Anthropic `metadata.user_id`,OpenAI 的 `session_id`、`conversation_id` 请求头、`prompt_cache_key` 与 `user`)中首个去掉首尾空白后非空者以 NUL 字符相连;没有客户端标识时为 API key 加 NUL 字符。Anthropic `metadata.user_id` 是带 `session_id` 的 JSON 时取 `session_id`,以 `_session_<十六进制与连字符>` 结尾时取该段,否则取原值;Gemini 与 Interactions 没有客户端标识
2. 摘要链:第 0 项为分区、客户端系统提示与工具声明的 SHA-256,第 i 项为第 i-1 项与第 i 条规范消息 JSON 的 SHA-256;公式与 JSON 编码见 [开发文档的运行目录](development.md#运行目录)
3. 匹配:会话记录保存上一次请求的链位置 L 与该处摘要;本次链的第 L 项等于该摘要,且满足下列之一时为同一会话:L 小于本次的消息条数;会话还没有成功生成过;最近一次成功生成的消息条数小于 L。取 L 最大者;并列时先取上一轮回答指纹与本次该位置的 assistant 消息一致者,再取最近使用者。回答指纹的算法同见运行目录
- 因此请求失败后原样重发时匹配同一会话;成功后原样重发时新建会话
4. 都不匹配时新建会话;编辑早期消息后链从该处分叉,得到新会话
3. 匹配:会话记录保存上一次请求的链位置 L 与该处摘要;本次链的第 L 项等于该摘要时为同一会话,本次不多于一条消息且会话已成功生成过时除外。取 L 最大者;并列时先取上一轮回答指纹与本次该位置的 assistant 消息一致者,再取最近使用者。回答指纹的算法同见运行目录
- 因此请求原样重发时匹配同一会话;只有一条消息的请求成功后原样重发时新建会话
4. 本次多于一条消息时另按回退匹配:会话记录还保存链位置 L 之前的全部链摘要,取从第 1 条消息起与本次相同部分最长的会话(并列时取最近使用者),相同部分比第 3 步匹配到的 L 更长时改用该会话,退回到相同部分的末尾继续使用,之前的消息沿用原来的时间;客户端回退、改写或替换较早的消息后仍是原会话
5. 仍没有时新建会话

序号为 `E` 的用户请求的执行 ID 为 `uuidOf("execution:" + cascade_id + ":" + E)`,`E` 以十进制写入,首个用户请求为 `:0`;`last_execution_id` 取序号 `E-1` 的执行 ID。`uuidOf(s)` 取 `SHA-256(s)` 前 16 字节,按 UUIDv4 设置版本与变体位后写成 `8-4-4-4-12` 形式。`requestId` 的时间段每次请求取当前毫秒。会话记录空闲 24 小时后删除。

Expand Down Expand Up @@ -2666,7 +2667,7 @@ Chat 与 Anthropic 的 Markdown 图片地址由 `MEDIA_OUTPUT` 决定:`inline`
- Gemini `candidateCount` 为 0 与省略时都为 1;超出范围时返回 400
- 流式时各候选的事件按到达顺序交错写出,带各自的 `index`
- 每个候选是一次完整的生成,各自选择账户并发出上游请求;候选同时开始,按「会话 ID」的规则共用一个会话:
- 新会话时第一个取得会话的候选新建会话,只有它发 ACL、标题请求与新会话事件;其余候选按第 3 步“链位置相同但尚未成功生成”匹配到这个会话
- 新会话时第一个取得会话的候选新建会话,只有它发 ACL、标题请求与新会话事件;其余候选按第 3 步链位置相同匹配到这个会话
- 每个成功的候选都写入会话记录:回答指纹与上游用量取最后完成的候选,各候选的思考签名合并保存
- 客户端以任一候选的回答续写都匹配这个会话
- 一个公开请求只记一条账本记录:`response_id` 为响应 ID,`attempts` 含全部候选的上游尝试,`account` 为最后一次分配的账户
Expand Down
43 changes: 38 additions & 5 deletions internal/service/conversation.go
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ import (
"maps"
"os"
"path/filepath"
"slices"
"sort"
"strings"
"sync"
"time"
Expand All @@ -23,12 +25,13 @@ const conversationTTL = 24 * time.Hour
// conversationTemp 为写入会话文件时同目录临时文件的名称前缀
const conversationTemp = ".conversation-"

// conversation 表示一个客户端会话的 cascade 与 trajectory 标识、最近一次请求在摘要链中的位置与其成功生成的回答指纹、各条消息首次出现的 Unix 秒、最近一次成功生成的上游输入用量、各函数调用 ID 与各回答指纹的思考签名、各签名摘要对应的模型族
// conversation 表示一个客户端会话的 cascade 与 trajectory 标识、最近一次请求在摘要链中的位置与该处的链摘要、该次请求成功生成的回答指纹、该位置之前供回退匹配的链摘要、各条消息首次出现的 Unix 秒、最近一次成功生成的上游输入用量、各函数调用 ID 与各回答指纹的思考签名、各签名摘要对应的模型族
type conversation struct {
Cascade string `json:"cascade"`
Trajectory string `json:"trajectory"`
Length int `json:"length"`
Digest string `json:"digest"`
Chain []string `json:"chain,omitempty"`
Answer string `json:"answer,omitempty"`
Times []int64 `json:"times"`
Prompt *promptUsage `json:"prompt,omitempty"`
Expand Down Expand Up @@ -143,31 +146,61 @@ func digest(previous string, data []byte) string {
return hex.EncodeToString(hash.Sum(nil))
}

// begin 为生成请求取得会话:先找最近一次请求是本次严格前缀的会话,其次找本次与之相同但尚未成功生成的会话,都没有时新建;记下本次的链位置与新消息的时间并落盘,返回会话副本,新建时副本的 New 为真
// begin 为生成请求取得会话:找最近一次请求是本次前缀或与本次相同的会话,本次不多于一条消息时不取已成功生成过的会话;本次多于一条消息时另由 rewind 取回退的会话,相同部分更长时改用它;都没有时新建;记下本次的摘要链与新消息的时间并落盘,返回会话副本,新建时副本的 New 为真
func (c *conversations) begin(digests, answers []string) (conversation, error) {
c.mu.Lock()
defer c.mu.Unlock()
now := c.now()
length := len(digests) - 1
item := c.match(digests, answers, func(item *conversation) bool {
return item.Length < length || item.Prompt == nil || item.Prompt.Length < item.Length
return length > 1 || item.Length < length || item.Prompt == nil || item.Prompt.Length < item.Length
})
shared := 0
if item != nil {
shared = item.Length
}
if length > 1 {
if back, kept := c.rewind(digests); kept > shared {
item, shared = back, kept
}
}
created := item == nil
if created {
item = &conversation{Cascade: uuid.NewString(), Trajectory: uuid.NewString()}
c.items[item.Cascade] = item
}
times := item.Times[:min(item.Length, len(item.Times))]
times := item.Times[:min(shared, len(item.Times))]
for len(times) < length {
times = append(times, now.Unix())
}
item.Length, item.Digest, item.Answer, item.Times, item.Used = length, digests[length], "", times, now
item.Length, item.Digest, item.Chain, item.Answer, item.Times, item.Used = length, digests[length], history(digests), "", times, now
c.sweep()
snapshot := c.snapshot(item)
snapshot.New = created
return snapshot, c.save(item)
}

// history 返回摘要链中链首之后、链位置之前各项的副本,链位置之前没有消息时为空
func history(digests []string) []string {
if len(digests) <= 2 {
return nil
}
return slices.Clone(digests[1 : len(digests)-1])
}

// rewind 返回从第 1 条消息起与本次相同条数最多的会话与相同条数:条数按会话保留的链摘要二分查找(链摘要逐项累积,某项相同则之前各项都相同),并列时取最近使用者;第 1 条消息就不同的会话不算,都不算时返回 nil 与 0
func (c *conversations) rewind(digests []string) (*conversation, int) {
var best *conversation
kept := 0
for _, item := range c.items {
count := sort.Search(min(len(item.Chain), len(digests)-1), func(i int) bool { return item.Chain[i] != digests[i+1] })
if count > kept || count > 0 && count == kept && item.Used.After(best.Used) {
best, kept = item, count
}
}
return best, kept
}

// find 返回链位置是本次前缀的会话副本,供计数使用且不改动记录
func (c *conversations) find(digests, answers []string) (conversation, bool) {
c.mu.Lock()
Expand Down
137 changes: 137 additions & 0 deletions internal/service/conversation_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,137 @@
package service

import (
"slices"
"testing"
"time"
)

// TestBeginKeepsConversationOfIdenticalRequest 验证成功后原样重发的请求归入原会话并沿用各消息的时间,之后一次多出几条消息的请求仍续接这个会话,改写已发消息与回退到早先消息的请求仍用原会话并沿用相同消息的时间,第一条消息不同的请求新建会话
func TestBeginKeepsConversationOfIdenticalRequest(t *testing.T) {
records, err := openConversations(t.TempDir())
if err != nil {
t.Fatal(err)
}
clock := time.Unix(1700000000, 0)
records.now = func() time.Time { return clock }
digests, answers := []string{"head", "first", "second", "third"}, []string{"", "reply", ""}
first, err := records.begin(digests, answers)
if err != nil || !first.New {
t.Fatalf("首次请求返回 %v,New 为 %v,期望新建会话", err, first.New)
}
if err := records.record(first.Cascade, digests, "answer", "model", 1, 10, signatureRecord{}); err != nil {
t.Fatal(err)
}
clock = clock.Add(4 * time.Minute)
again, err := records.begin(digests, answers)
if err != nil || again.New || again.Cascade != first.Cascade || again.Trajectory != first.Trajectory || !slices.Equal(again.Times, first.Times) {
t.Fatalf("原样重发返回 %v,会话 %s 时间 %v,期望原会话 %s 时间 %v", err, again.Cascade, again.Times, first.Cascade, first.Times)
}
next, err := records.begin([]string{"head", "first", "second", "third", "fourth", "fifth"}, []string{"", "reply", "", "answer", ""})
if err != nil || next.New || next.Cascade != first.Cascade || next.Times[0] != first.Times[0] {
t.Fatalf("续接请求返回 %v,会话 %s 时间 %v,期望原会话 %s 且首条时间不变", err, next.Cascade, next.Times, first.Cascade)
}
clock = clock.Add(time.Minute)
edited, err := records.begin([]string{"head", "first", "second", "third", "fourth", "changed", "sixth", "seventh"}, []string{"", "reply", "", "answer", "", "", ""})
if err != nil || edited.New || edited.Cascade != first.Cascade || !slices.Equal(edited.Times[:4], next.Times[:4]) || edited.Times[4] != clock.Unix() {
t.Fatalf("改写已发消息的请求返回 %v,会话 %s 时间 %v,期望原会话 %s、前 4 条时间不变、其后为当前时间", err, edited.Cascade, edited.Times, first.Cascade)
}
back, err := records.begin([]string{"head", "first", "second"}, []string{"", "reply"})
if err != nil || back.New || back.Cascade != first.Cascade || !slices.Equal(back.Times, first.Times[:2]) {
t.Fatalf("回退的请求返回 %v,会话 %s 时间 %v,期望原会话 %s 与前 2 条的时间", err, back.Cascade, back.Times, first.Cascade)
}
other, err := records.begin([]string{"head", "another", "more"}, []string{"", ""})
if err != nil || !other.New {
t.Fatalf("第一条消息不同的请求返回 %v,New 为 %v,期望新建会话", err, other.New)
}
}

// TestBeginStartsConversationForRepeatedFirstMessage 验证只有一条消息的请求成功后原样重发时新建会话
func TestBeginStartsConversationForRepeatedFirstMessage(t *testing.T) {
records, err := openConversations(t.TempDir())
if err != nil {
t.Fatal(err)
}
digests := []string{"head", "first"}
first, err := records.begin(digests, []string{""})
if err != nil {
t.Fatal(err)
}
if err := records.record(first.Cascade, digests, "answer", "model", 1, 10, signatureRecord{}); err != nil {
t.Fatal(err)
}
again, err := records.begin(digests, []string{""})
if err != nil || !again.New || again.Cascade == first.Cascade {
t.Fatalf("原样重发返回 %v,会话 %s,New 为 %v,期望新建会话", err, again.Cascade, again.New)
}
}

// TestRewindToEarlierMessage 验证从任意更早的消息处回退、改写或截短的请求仍用原会话,第一条消息不同的请求新建会话
func TestRewindToEarlierMessage(t *testing.T) {
records, err := openConversations(t.TempDir())
if err != nil {
t.Fatal(err)
}
base := []string{"head", "m1", "m2", "m3", "m4", "m5", "m6"}
for _, test := range []struct {
name string
request []string
same bool
}{
{"回退一条", []string{"head", "m1", "m2", "m3", "m4", "m5", "x", "y"}, true},
{"改写第二条后保留其后的消息", []string{"head", "m1", "x", "m3", "m4", "m5", "m6", "y"}, true},
{"截短到第二条", []string{"head", "m1", "m2"}, true},
{"第一条不同", []string{"head", "x", "m2", "m3"}, false},
} {
// 各用例的消息摘要带用例名,在同一个目录中互不匹配
mark := func(digests []string) []string {
marked := []string{digests[0]}
for index := range digests[1:] {
marked = append(marked, digest(marked[index], []byte(test.name+digests[index+1])))
}
return marked
}
first, err := records.begin(mark(base), make([]string, len(base)-1))
if err != nil {
t.Fatal(err)
}
next, err := records.begin(mark(test.request), make([]string, len(test.request)-1))
if err != nil || (next.Cascade == first.Cascade) != test.same || next.New == test.same {
t.Fatalf("%s:返回 %v,会话 %s,New 为 %v,原会话 %s,期望沿用原会话为 %v", test.name, err, next.Cascade, next.New, first.Cascade, test.same)
}
}
}

// TestRewindPrefersLongerSharedConversation 验证另有一个只含相同首条消息的会话时,改写长会话最后一条消息的请求仍回到长会话,并沿用长会话中相同消息的时间
func TestRewindPrefersLongerSharedConversation(t *testing.T) {
records, err := openConversations(t.TempDir())
if err != nil {
t.Fatal(err)
}
clock := time.Unix(1700000000, 0)
records.now = func() time.Time { return clock }
chained := func(messages ...string) []string {
digests := []string{"head"}
for index, message := range messages {
digests = append(digests, digest(digests[index], []byte(message)))
}
return digests
}
long, err := records.begin(chained("first", "reply", "second"), make([]string, 3))
if err != nil {
t.Fatal(err)
}
if err := records.record(long.Cascade, chained("first", "reply", "second"), "answer", "model", 3, 10, signatureRecord{}); err != nil {
t.Fatal(err)
}
clock = clock.Add(time.Minute)
short, err := records.begin(chained("first"), make([]string, 1))
if err != nil || !short.New {
t.Fatalf("以相同首条消息新开的请求返回 %v,New 为 %v,期望新建会话", err, short.New)
}
clock = clock.Add(time.Minute)
edited, err := records.begin(chained("first", "reply", "changed"), make([]string, 3))
if err != nil || edited.Cascade != long.Cascade || !slices.Equal(edited.Times[:2], long.Times[:2]) || edited.Times[2] != clock.Unix() {
t.Fatalf("改写长会话最后一条的请求返回 %v,会话 %s 时间 %v,期望长会话 %s、前 2 条时间 %v、第 3 条为当前时间", err, edited.Cascade, edited.Times, long.Cascade, long.Times[:2])
}
}