6.4 KiB

Raw Blame History

Grounding分析实现文档

概述

我们在 EnhancedMarkdownRenderer 组件中实现了一个强大的功能：将Markdown节点与引用资源进行关联分析。这个功能可以识别文档中哪些部分有引用支持，并提供可视化指示器。

🔍 功能特性

1. 类型分析

MarkdownNode 类型

interface MarkdownNode {
  node_type: MarkdownNodeType;     // 节点类型（标题、段落、链接等）
  content: string;                 // 节点内容（原始文本）
  range: Range;                    // 位置范围（行号、列号、字符偏移）
  children: MarkdownNode[];        // 子节点
  attributes: Record<string, string>; // 节点属性
}

GroundingMetadata 类型

interface GroundingMetadata {
  sources: GroundingSource[];           // 引用来源列表
  search_queries: string[];             // 搜索查询
  grounding_supports?: GroundingSupport[]; // 支持信息（关联文字片段与来源）
}

interface GroundingSupport {
  groundingChunkIndices: number[];      // 关联的来源索引
  segment: GroundingSegment;            // 文字片段信息
}

interface GroundingSegment {
  start_index: number;                  // 片段开始位置
  end_index: number;                    // 片段结束位置
}

2. 关联算法

位置匹配逻辑

const analyzeNodeGrounding = useCallback((node: MarkdownNode) => {
  if (!groundingMetadata?.grounding_supports || !parseResult) {
    return null;
  }

  // 计算节点在原始文本中的字符偏移位置
  const nodeStartOffset = node.range?.start?.offset || 0;
  const nodeEndOffset = node.range?.end?.offset || 0;
  
  // 查找与当前节点位置重叠的grounding支持信息
  const relatedSupports = groundingMetadata.grounding_supports.filter(support => {
    const segmentStart = support.segment.start_index;
    const segmentEnd = support.segment.end_index;
    
    // 检查节点范围与grounding片段是否有重叠
    return (nodeStartOffset <= segmentEnd && nodeEndOffset >= segmentStart);
  });

  // 处理关联结果...
}, [groundingMetadata, parseResult]);

关键算法特点

重叠检测: 通过比较字符偏移位置判断节点与grounding片段是否重叠
来源关联: 根据 groundingChunkIndices 获取相关的引用来源
详细分析: 提供节点信息、位置信息和关联的引用资源

3. 可视化指示器

引用标记

const GroundingIndicator = groundingAnalysis ? (
  <span 
    className="inline-flex items-center ml-1 px-1 py-0.5 text-xs bg-blue-100 text-blue-700 rounded cursor-help"
    title={`引用了 ${groundingAnalysis.groundingInfo.sourceCount} 个来源`}
    onClick={() => {
      console.log('📚 点击查看引用详情:', groundingAnalysis);
    }}
  >
    📚 {groundingAnalysis.groundingInfo.sourceCount}
  </span>
) : null;

显示位置

标题节点: 在标题后显示引用指示器
段落节点: 在段落后显示引用指示器
其他节点: 可根据需要扩展

4. 调试和分析

控制台输出

console.log('🔗 节点引用分析:', {
  node: {
    type: node.node_type,
    content: node.content.substring(0, 100) + '...',
    position: {
      start: nodeStartOffset,
      end: nodeEndOffset,
      line: node.range?.start?.line,
      column: node.range?.start?.column
    }
  },
  groundingInfo: {
    supportCount: relatedSupports.length,
    sourceCount: relatedSources.length,
    sources: relatedSources.map(source => ({
      title: source.title,
      uri: source.uri,
      snippet: source.content?.snippet || 'No snippet available'
    })),
    segments: relatedSupports.map(support => ({
      start: support.segment.start_index,
      end: support.segment.end_index,
      chunkIndices: support.groundingChunkIndices
    }))
  }
});

🛠️ 技术实现

1. 组件集成

在 EnhancedMarkdownRenderer 中添加了：

analyzeNodeGrounding 函数：分析节点与引用的关联
GroundingIndicator 组件：可视化引用指示器
在关键节点类型中显示指示器

2. Key唯一性修复

为了解决React key重复警告，改进了key生成逻辑：

const key = `${node.range?.start?.line || 0}-${node.range?.start?.column || 0}-${node.range?.start?.offset || 0}-${depth}-${index}`;

3. 性能优化

使用 useCallback 缓存分析函数
只在有grounding数据时进行分析
避免不必要的重复计算

📋 使用示例

基本用法

<EnhancedMarkdownRenderer
  content={markdownContent}
  enableMarkdown={true}
  enableReferences={true}
  groundingMetadata={groundingData}
/>

完整示例

参见 GroundingAnalysisExample.tsx 文件，包含：

模拟的grounding数据
完整的UI展示
详细的功能说明

🔍 分析结果

输出格式

{
  node: {
    type: "Paragraph",
    content: "人工智能技术在近年来取得了显著进展...",
    position: {
      start: 15,
      end: 85,
      line: 2,
      column: 0
    }
  },
  groundingInfo: {
    supportCount: 1,
    sourceCount: 1,
    sources: [{
      title: "AI技术发展白皮书2024",
      uri: "https://ai-research.org/whitepaper-2024",
      snippet: "人工智能技术在深度学习、自然语言处理等领域取得重大突破..."
    }],
    segments: [{
      start: 15,
      end: 85,
      chunkIndices: [0]
    }]
  }
}

🎯 应用场景

学术文档: 显示引用来源和支持材料
研究报告: 标识数据来源和参考文献
AI生成内容: 显示训练数据来源和可信度
知识管理: 追踪信息来源和关联关系

🚀 扩展可能

弹窗详情: 点击指示器显示详细引用信息
侧边栏: 显示完整的引用列表
高亮显示: 鼠标悬停时高亮相关文本
导出功能: 生成引用列表和参考文献
可信度评分: 根据来源质量显示可信度

📝 总结

这个实现成功地将Markdown节点与引用资源进行了关联，提供了：

✅ 精确的位置匹配算法
✅ 可视化的引用指示器
✅ 详细的分析输出
✅ 良好的性能和用户体验
✅ 可扩展的架构设计

通过这个功能，用户可以清楚地看到文档中哪些部分有引用支持，并能够深入了解引用的详细信息，大大提升了文档的可信度和可追溯性。

6.4 KiB Raw Blame History Unescape Escape