Guidance项目中的HTML标签污染问题解析与解决方案

问题背景

在使用Guidance项目与大型语言模型(如Llama-3 8B/70B和Mixtral)交互时，开发者发现gen函数生成的输出被不必要的HTML标签包裹，导致难以直接提取所需内容。这些HTML标签不仅污染了输出格式，还增加了后续数据处理的复杂度。

问题现象

当使用gen函数生成文本时，模型会在输出中插入类似以下结构的HTML标签：

<||_html:<span style='background-color: rgba(0.0, 165.0, 0, 0.15); border-radius: 3px;' title='1.0'>_||>

这些标签将每个字符或单词单独包裹，使得原本简洁的JSON格式输出变得难以解析。

技术分析

经过深入分析，这个问题并非Guidance框架本身的缺陷，而是与模型输出处理和结果提取方式有关。关键点在于：

1. 输出显示与存储分离：当设置echo=True时，控制台显示的是原始输出流，包含模型生成的所有中间格式和标记。

2. 结构化数据提取：Guidance实际上在内部已经正确解析了生成内容，但需要通过特定API访问而非直接打印整个输出对象。

解决方案

方法一：禁用回显模式

在初始化模型时设置echo=False可以避免控制台显示被污染的原始输出：

llm = models.Transformers(
    model_id, 
    echo=False,  # 关键修改
    cache_dir="/data2/.shared_models/", 
    device_map='auto'
)

方法二：使用正确的结果提取方式

更推荐的方法是使用Guidance提供的API直接获取生成内容：

1. 按名称提取生成结果：

substance_use = llm["Substance"]  # 提取select结果
explanation = llm["Substance Use Explanation"]  # 提取gen结果

2. 使用capture函数捕获大段文本： 对于包含多个生成操作和普通文本的复杂输出，可以使用capture函数：

from guidance import capture

@guidance
def complex_generation(lm):
    with capture("full_output"):
        lm += "前缀文本"
        lm += gen("part1")
        lm += "中间文本"
        lm += gen("part2")
    return lm

result = llm + complex_generation()
full_output = result["full_output"]  # 获取完整捕获内容

最佳实践建议

1. 避免依赖原始输出：始终使用Guidance提供的API方法提取生成内容，而非直接解析原始输出字符串。

2. 合理命名生成操作：为每个gen和select操作赋予有意义的名称，便于后续提取。

3. 分层处理复杂输出：对于嵌套或多层次的生成内容，采用分层捕获和提取策略。

4. 输出验证：在提取关键数据后，添加验证逻辑确保数据完整性。

总结

Guidance框架通过提供结构化的结果提取API，有效解决了模型原始输出中的格式污染问题。开发者应当熟悉框架提供的数据访问模式，而非依赖传统的字符串解析方法。这种设计既保持了与模型交互的灵活性，又确保了结果提取的可靠性，是大型语言模型应用开发中的一种优雅解决方案。