streamlit-add-chat-page

用途

本技能用于为 Streamlit in Snowflake（SiS）应用构建“与数据对话”的聊天页面。根据数据类型分为两条路径：

• 路径 A（结构化数据）：适用于表格、指标等可聚合的行数据。使用 Cortex Analyst 将自然语言问题转换为针对语义视图的 SQL，执行后展示结果和简短回答。
• 路径 B（非结构化数据）：适用于文档、分块文本等自由文本。使用 Cortex Search RAG 检索最相关的文本块，并合成有依据、带引用的回答。

两条路径共享相同的聊天界面模式：多轮对话、展开面板、反馈和防护措施。

主要能力

• 提供语义层 SQL、聊天页面和评估工具的模板文件：路径 A 使用 references/semantic_layer.sql、references/chat_page.py、references/eval_harness.py；路径 B 使用 references/cortex_search_rag.sql、references/rag_chat_page.py。
• 路径 A 支持：语义视图建模、命名指标、同义词与注释、已验证查询、AI_SQL_GENERATION 领域规则、Cortex Search 字面量解析、多轮对话、SQL 执行与结果展示、AI_COMPLETE 生成回答、反馈记录、回归测试。
• 路径 B 支持：文档分块、Cortex Search 服务创建、检索与合成、引用来源、多轮对话、反馈记录。

使用方式

路径 A：结构化数据（Cortex Analyst）

1. 建模语义层：将数据扁平化为一个视图，完成所有连接和预计算列。在该视图上创建语义视图（CREATE SEMANTIC VIEW），定义维度和指标，为每个表/维度/指标添加 WITH SYNONYMS 和 COMMENT。使用命名指标编码派生指标。添加已验证查询（AI_VERIFIED_QUERIES）和 AI_SQL_GENERATION 领域规则。
2. 修复字面量解析：对高基数（>10 个不同值）的字符串维度，附加 Cortex Search 服务（WITH CORTEX SEARCH SERVICE <fqn> USING <col>）；低基数（1-10）提供样本值。
3. 构建聊天页面：适配 references/chat_page.py。实现 Analyst REST 调用、多轮消息累积、直接运行返回的 SQL、通过 AI_COMPLETE 生成回答、展开面板、示例问题按钮、空结果处理、防护措施（只读 SELECT/WITH、行数限制、最小权限角色）、反馈循环。
4. 部署与验证：部署应用，使用 cortex analyst query 验证模型，运行回归测试工具。

路径 B：非结构化文档（Cortex Search RAG）

1. 分块文档并创建搜索服务：获取分块表（每行一个块加源元数据）。使用 AI_PARSE_DOCUMENT 提取文本，SNOWFLAKE.CORTEX.SPLIT_TEXT_RECURSIVE_CHARACTER 分块。在块文本列上创建 Cortex Search 服务，设置 ATTRIBUTES 和 TARGET_LAG。使用 SEARCH_PREVIEW 验证检索质量。
2. 构建 RAG 聊天页面：适配 references/rag_chat_page.py。实现检索、合成（仅使用检索到的块，要求引用来源，不知道时回答“我不知道”）、引用来源展开面板、多轮对话、示例按钮、反馈记录、无相关结果消息。
3. 部署与验证：部署应用，提问已知答案的问题，确认回答正确且引用块支持答案。

适用场景

• 需要为 SiS 应用添加自然语言查询结构化数据的能力。
• 需要为 SiS 应用添加基于文档的问答能力。
• 需要多轮对话、反馈收集和回归测试的聊天界面。

限制

• 不适用于单一固定仪表板图表，直接写 SQL 即可。
• 不适用于需要跨域编排多个工具的单一聊天，应使用 Cortex Agent。
• 路径 A 中，语义视图应为单表，避免一对多连接导致行重复和聚合膨胀。
• 路径 B 中，分块大小和重叠需要调整，检索质量依赖分块策略。
• 需要 Snowflake 环境、Cortex 访问权限和适当的角色授权。
• 部署前需要审批 DDL 和部署命令。
• 部分功能（如 Cortex Agent）超出本技能范围。

注意事项

• 使用 AI_COMPLETE，而非已弃用的 SNOWFLAKE.CORTEX.COMPLETE。
• 每项 COMMENT 需要 =：COMMENT = '...'。
• 维度子句顺序固定：表达式 → WITH SYNONYMS → COMMENT → WITH CORTEX SEARCH SERVICE。
• 搜索服务名称需完全限定（DB.SCHEMA.NAME）。
• 搜索服务有 TARGET_LAG，新值在刷新后可模糊匹配，精确匹配始终立即生效。
• 助手回合应计算后一次性渲染，避免内联渲染。
• RESULT_SCAN / 会话状态在池化连接中不保留，需重新查询对象验证 DDL。