> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Text-to-Chart

> 在 ClickStack 中使用 AI 驱动的 Text-to-Chart 功能，根据自然语言提示词生成图表。

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

ClickStack 的 Text-to-Chart 功能可让你通过用自然语言描述想查看的内容来创建可视化。你无需手动选择指标、过滤器和分组字段，只需输入类似“过去 24 小时内按服务划分的错误率”这样的提示词，ClickStack 就会自动生成相应的图表。

该功能使用大语言模型 (LLM) 将文本提示词转换为查询，然后在 [Chart Explorer](/zh/clickstack/features/dashboards/overview#navigate-chart-explorer) 中生成可视化。它适用于任何已配置的数据源。

<div id="prerequisites">
  ## 前置条件
</div>

Text-to-Chart 需要一个 [Anthropic API 密钥](https://console.anthropic.com/)。启动 ClickStack 时，请设置 `ANTHROPIC_API_KEY` 环境变量。

对于开源部署，请将该密钥作为环境变量传入。具体方式因部署类型而异：

<Tabs>
  <Tab title="Docker（All-in-One 或本地模式）">
    ```bash theme={null}
    docker run -e ANTHROPIC_API_KEY='<YOUR_KEY>' -p 8080:8080 -p 4317:4317 -p 4318:4318 clickhouse/clickstack-all-in-one:latest
    ```
  </Tab>

  <Tab title="Docker（仅 HyperDX）">
    ```bash theme={null}
    docker run -e ANTHROPIC_API_KEY='<YOUR_KEY>' -p 8080:8080 docker.hyperdx.io/hyperdx/hyperdx-local
    ```
  </Tab>

  <Tab title="Docker Compose">
    将该变量添加到 `.env` 文件中，或直接在 `docker-compose.yaml` 中设置：

    ```yaml theme={null}
    services:
      app:
        environment:
          ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
    ```
  </Tab>

  <Tab title="Helm">
    使用 `--set` 传入该密钥：

    ```bash theme={null}
    helm install my-hyperdx hyperdx/hdx-oss-v2 \
      --set env[0].name=ANTHROPIC_API_KEY \
      --set env[0].value=<YOUR_KEY>
    ```
  </Tab>
</Tabs>

<div id="using-text-to-chart">
  ## 使用Text-to-Chart
</div>

<Steps>
  <Step>
    ### 前往Chart Explorer

    在 HyperDX 中，从左侧菜单选择 **Chart Explorer**。
  </Step>

  <Step>
    ### 选择数据源

    选择要可视化的数据源，例如 **日志**、**链路追踪** 或 **指标**。

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/Q67DpMkcKgzQJkGD/images/clickstack/text-to-chart/chart-explorer.png?fit=max&auto=format&n=Q67DpMkcKgzQJkGD&q=85&s=2fae14338464d6b3f07dc9775e412cfa" alt="图表浏览器" width="3808" height="760" data-path="images/clickstack/text-to-chart/chart-explorer.png" />
  </Step>

  <Step>
    ### 输入文本提示词

    在Chart Explorer顶部找到 **AI 助手** 输入框。输入你想创建的图表的自然语言描述。例如：

    * `按 service 查看过去 24 小时的错误率`
    * `按 endpoint 查看延迟明细`
    * `按严重程度分组统计事件数量随时间的变化`

    ClickStack 会将提示词转换为查询，并自动渲染可视化结果。

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/Q67DpMkcKgzQJkGD/images/clickstack/text-to-chart/text-to-chart.png?fit=max&auto=format&n=Q67DpMkcKgzQJkGD&q=85&s=e8851dcb524d71d9adae57650e3b6634" alt="文本生成图表" width="1905" height="969" data-path="images/clickstack/text-to-chart/text-to-chart.png" />
  </Step>
</Steps>

<div id="demo-data">
  ## 使用演示数据试用
</div>

试用 Text-to-Chart 最快捷的方式，是使用 [本地模式](/zh/clickstack/deployment/local-mode-only) Docker 镜像和[远程演示数据集](/zh/clickstack/example-datasets/remote-demo-data)：

```bash theme={null}
docker run -e ANTHROPIC_API_KEY='<YOUR_KEY>' -p 8080:8080 clickhouse/clickstack-local:latest
```

访问 `localhost:8080`。要连接到演示数据，请前往 **团队设置**，并使用以下信息创建新连接：

* **连接名称**: `Demo`
* **主机**: `https://sql-clickhouse.clickhouse.com`
* **用户名**: `otel_demo`
* **密码**: 留空

<Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8a08bda2/Q67DpMkcKgzQJkGD/images/clickstack/text-to-chart/create-connection.png?fit=max&auto=format&n=Q67DpMkcKgzQJkGD&q=85&s=e606c37288c529e2647fe9a6b231a946" alt="创建连接" width="3810" height="1502" data-path="images/clickstack/text-to-chart/create-connection.png" />

然后将各个数据源——**日志**、**链路追踪**、**指标** 和 **会话**——修改为使用 `otel_v2` 数据库。有关配置数据源的完整说明，请参阅[远程演示数据集指南](/zh/clickstack/example-datasets/remote-demo-data)。

连接完成后，打开 **Chart Explorer**，使用可用的日志、链路追踪和指标试试这些提示词。

<div id="example-prompts">
  ## 示例提示词
</div>

以下提示词展示了处理可观测性数据时的常见用法：

| 提示词                                               | 数据源  | 描述              |
| ------------------------------------------------- | ---- | --------------- |
| `Error count by service over time`                | 日志   | 以图表形式展示各服务的错误频率 |
| `Average request duration grouped by endpoint`    | 链路追踪 | 展示各端点的延迟模式      |
| `P99 latency by service`                          | 链路追踪 | 识别各服务的尾延迟       |
| `Count of 5xx status codes over the last 6 hours` | 日志   | 跟踪服务器错误趋势       |

提示词可以引用已配置数据源中任何可用的列或 attribute。提示词越具体，生成的图表就越准确。

<div id="limitations">
  ## 限制
</div>

* Text-to-Chart 目前仅支持 Anthropic 作为 LLM 提供商。对包括 OpenAI 在内的更多提供商的支持预计将在后续版本中推出。
* 目前仅支持日志和链路追踪作为数据源。暂不支持 Prometheus 指标。
* 图表的准确性取决于 提示词 的清晰程度以及底层数据的结构。如果生成的图表不符合预期，请尝试改写 提示词，或明确指定列名。

<div id="further-reading">
  ## 延伸阅读
</div>

* [从文本到图表：用 ClickStack 更快实现可视化](https://clickhouse.com/blog/text-to-charts-faster-way-to-visualize-clickstack) — 介绍该功能的博客文章
* [仪表盘和可视化](/zh/clickstack/features/dashboards/overview) — 使用 Chart Explorer 手动创建图表
* [搜索](/zh/clickstack/features/search) — 全文搜索和属性搜索语法
* [配置](/zh/clickstack/managing/config) — ClickStack 的所有环境变量