OpenViking 上下文数据库 Golang 集成实践

1.3 目录递归检索策略

传统的向量检索采用扁平搜索，忽略了文档的层级结构。OpenViking 创新性地实现了目录递归检索策略：

检索流程：

1. 意图分析：生成多个检索条件，理解查询的深层意图
2. 全局向量搜索：找到 top-3 最相关的目录作为'种子'
3. 递归精细探索：在种子目录下进行二次检索，逐层深入子目录
4. 分数传播：score = α × child_score + (1-α) × parent_score
5. 收敛检测：top-k 结果连续 3 轮不变时提前停止

算法优势：

• 全局相关性：不仅考虑内容相似性，还考虑上下文环境
• 效率优化：优先探索高分目录，减少无效搜索
• 可解释性：完整记录检索路径，便于调试优化

1.4 双存储架构设计

OpenViking 采用内容与索引分离的双存储架构：

┌─────────────────────────────────────────────────────────┐
│ VikingFS (URI 抽象层) │
│ 统一的 URI 映射/文件操作/关系管理 │
└─────────────────────┬───────────────────────────────────┘
                      │
┌────────────┴────────────┐
▼ ▼
┌───────────────────┐ ┌───────────────────┐
│ AGFS              │ │ VectorDB          │
│ (内容存储)        │ │ (索引存储)        │
│                   │ │                   │
│ • L0/L1/L2 文件   │ │ • URI 索引        │
│ • 多媒体资源      │ │ • Dense 向量      │
│ • 关系 JSON       │ │ • Sparse 向量     │
│                   │ │ • 标量元数据      │
└───────────────────┘ └───────────────────┘

存储分离的优势：

• 性能优化：VectorDB 专注索引检索，AGFS 专注内容存储
• 数据一致性：通过 URI 关联，确保索引与内容同步
• 扩展性：支持独立扩展存储层和索引层
• 容错性：单层故障不影响整体系统

第二部分：Golang 客户端完整实现

2.1 整体架构设计

// pkg/openviking/client.go
package openviking

import (
	"context"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"strings"
	"time"
)

// ClientConfig 客户端配置
type ClientConfig struct {
	Endpoint  string        // OpenViking 服务端点
	APIKey    string        // API 密钥
	Timeout   time.Duration // 请求超时时间
	MaxRetries int          // 最大重试次数
	EnableDebug bool        // 调试模式
}

// VikingClient OpenViking 客户端
type VikingClient struct {
	config      *ClientConfig
	httpClient  *http.Client
	baseURL     string
	retryPolicy *RetryPolicy
}

// Context 上下文对象
type Context struct {
	URI         string     // 唯一标识符
	Abstract    string     // L0 摘要
	Overview    string     // L1 概述
	Detail      string     // L2 详情
	Metadata    map[string]string // 元数据
	CreatedAt   time.Time // 创建时间
	UpdatedAt   time.Time // 更新时间
	Relations   []Relation // 关联关系
}

// Relation 关联关系
type Relation struct {
	TargetURI    string  // 目标 URI
	RelationType string  // 关系类型：contains, references, derived_from 等
	Strength     float64 // 关系强度（0-1）
}

// SearchResult 搜索结果
type SearchResult struct {
	Contexts []*Context // 上下文列表
	Scores   []float64  // 匹配分数
	Total    int        // 总结果数
	Took     time.Duration // 搜索耗时
	DebugInfo *DebugInfo // 调试信息
}

// DebugInfo 调试信息
type DebugInfo struct {
	QueryParsed       string   // 解析后的查询
	SeedDirectories   []string // 种子目录
	RecursionDepth    int      // 递归深度
	CandidatesGenerated int     // 候选生成数
	RetrievalPath     []RetrievalStep // 检索路径
}

// NewClient 创建新的 OpenViking 客户端
func NewClient(config *ClientConfig) (*VikingClient, error) {
	if config.Endpoint == "" {
		return nil, fmt.Errorf("endpoint is required")
	}
	// 确保 URL 以/结尾
	endpoint := config.Endpoint
	if !strings.HasSuffix(endpoint, "/") {
		endpoint = endpoint + "/"
	}
	client := &VikingClient{
		config: config,
		httpClient: &http.Client{
			Timeout: config.Timeout,
			Transport: createTransport(config),
		},
		baseURL:     endpoint + "api/v1/",
		retryPolicy: NewExponentialBackoffRetry(),
	}
	// 初始化连接池
	if err := client.initializeConnectionPool(); err != nil {
		return nil, fmt.Errorf("failed to initialize connection pool: %w", err)
	}
	return client, nil
}

// createTransport 创建 HTTP 传输层
func createTransport(config *ClientConfig) *http.Transport {
	return &http.Transport{
		MaxIdleConns:        100,
		MaxIdleConnsPerHost: 20,
		IdleConnTimeout:     90 * time.Second,
		TLSHandshakeTimeout: 10 * time.Second,
		ExpectContinueTimeout: 1 * time.Second,
	}
}

2.2 核心 API 实现

// pkg/openviking/api.go
package openviking

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"strconv"
)

// PutContext 存储上下文（支持重试机制）
func (c *VikingClient) PutContext(ctx context.Context, vikingContext *Context) error {
	// 构建请求体
	requestBody := map[string]interface{}{
		"uri":      vikingContext.URI,
		"abstract": vikingContext.Abstract,
		"overview": vikingContext.Overview,
		"detail":   vikingContext.Detail,
		"metadata": vikingContext.Metadata,
		"relations": vikingContext.Relations,
	}
	jsonBody, err := json.Marshal(requestBody)
	if err != nil {
		return fmt.Errorf("failed to marshal request body: %w", err)
	}
	// 执行带重试的请求
	return c.retryPolicy.ExecuteWithRetry(ctx, func() error {
		req, err := http.NewRequestWithContext(ctx, "POST", c.baseURL+"contexts", bytes.NewReader(jsonBody))
		if err != nil {
			return fmt.Errorf("failed to create request: %w", err)
		}
		// 设置请求头
		req.Header.Set("Content-Type", "application/json")
		req.Header.Set("Authorization", "Bearer "+c.config.APIKey)
		req.Header.Set("X-Request-ID", generateRequestID())
		// 发送请求
		resp, err := c.httpClient.Do(req)
		if err != nil {
			return fmt.Errorf("failed to send request: %w", err)
		}
		defer resp.Body.Close()
		// 处理响应
		if resp.StatusCode != http.StatusCreated && resp.StatusCode != http.StatusOK {
			body, _ := io.ReadAll(resp.Body)
			return &APIError{
				StatusCode: resp.StatusCode,
				Message:    string(body),
				Operation:  "PutContext",
			}
		}
		return nil
	})
}

// GetContext 获取上下文（支持分层加载）
func (c *VikingClient) GetContext(ctx context.Context, uri string, options *GetOptions) (*Context, error) {
	url := c.baseURL + "contexts/" + strings.TrimPrefix(uri, "viking://")
	req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
	if err != nil {
		return nil, fmt.Errorf("failed to create request: %w", err)
	}
	// 设置请求参数
	req.Header.Set("Authorization", "Bearer "+c.config.APIKey)
	if options != nil {
		if options.RetrieveLevel != "" {
			req.Header.Set("X-Context-Level", options.RetrieveLevel)
		}
		if options