Wren AI的工作原理

Wren AI 是一款将自然语言用户查询转化为SQL的工具，业内通常称之为“文本到SQL”（Text-to-SQL），或者NL2SQL。简单来说，它让你能用自然语言直接跟数据库对话。它同时提供了UI界面和API接口，能根据你输入的问题自动生成SQL查询，再用这些查询去捞数据。这在搭建RAG（检索增强生成）或Agent（智能袋里）应用时，处理结构化表格数据变得格外顺手。

部署Wren AI倒不算复杂，官方的Docker Compose文件可以直接在本地跑起来。你只需要一个OpenAI的API密钥，再选好打算用的模型就行。当然，如果你偏好其他推理引擎，比如LocalAI，也可以通过设置容器的`OPENAI_API_BASE`环境变量来接入。Wren AI团队还集成了Ollama推理，并且推荐使用Llama3 70b-instruct模型。要是想用OpenAI之外的模型，就需要在`~/.wrenai/.env.ai`文件里手动配置一下——下面这段示例应该能帮你快速上手。

### Example: Ollama inference
LLM_PROVIDER=ollama

### ollama. URL should be reachable from Docker Container!!!
OLLAMA_URL=http://host.docker.internal:11434

### https://ollama.com/library/llama3:70b-instruct-q8_0
GENERATION_MODEL=llama3:70b-instruct-q8_0

### supported embedding models providers by qdrant: https://qdrant.tech/documentation/embeddings/
### https://ollama.com/library/mxbai-embed-large:335m-v1-fp16
EMBEDDING_MODEL=mxbai-embed-large:335m-v1-fp16
EMBEDDING_MODEL_DIMENSION=1024

### DOCUMENT_STORE
DOCUMENT_STORE_PROVIDER=qdrant
QDRANT_HOST=qdrant

目前支持的数据库阵容还挺全的，包括BigQuery、DuckDB、PostgreSQL、MySQL、MS SQL、Clickhouse，甚至连Microsoft Excel插件也囊括在内。如果你想为其他数据库投票，可以在官方渠道找到入口。

安装完成后，通过浏览器访问对应的URL就能进入主界面。

连接到实际数据库或者上传示例数据集（比如NBA游乐场）之后，就会进入主页面。如果你想查看示例数据集的具体内容，可以通过调整URL中的`DATASET_VERSION`变量来定位。

这里有一个非常关键的步骤：在“建模”菜单里配置好数据表的关系，并添加一些描述性的文本。这一步很关键——它就像给数据库建索引一样，能帮助你和背后的LLM更好地理解数据和元数据。

建模的目的是让大型语言模型（LLM）掌握数据的结构和含义，从而给出更精准的查询结果。仅仅靠表中列的API名称是远远不够的，所以必须设置好表之间的关系，并为关键字段补充描述。

在建模菜单里配置好模式关系并添加描述后，回到“主页”菜单，就可以测试你的第一个文本到SQL查询了。系统会尝试为你生成三种不同的SQL查询方案，结果会直接展示在界面上。

优质内容：API

除了UI界面，Wren AI也提供了API接口，方便你把结构化数据集成到自己的RAG或Agent管道应用中。不过目前有个小遗憾：Wren AI还不支持WebSocket、Server-Sent Events或WebHooks这种实时推送机制。如果你想获取更新，得靠客户端发起长轮询来不断检查任务状态——好消息是，团队已经在解决这个问题了。

虽然目前没有公开的API文档，但借助Chrome开发者工具的“网络”面板，还是能捕捉到完整的交互流程。具体操作如下：

1. 在GraphQL中通过`createAskingTask`变更提交一个问题，这会创建一个异步任务。

2. 使用`askingTask`查询来轮询任务的状态变化。

3. 当状态变为`FINISHED`后，从返回的payload中提取三个候选结果。

4. 用获取到的payload调用`createThread`变更。

5. 一个线程包含多个响应，每个响应里都涵盖了一个问题和一个答案。通过`thread`查询可以拉取整个线程。

6. 每个线程的`responses`字段是一个响应数组，后续的问题会持续追加到这个数组里。

7. 持续轮询`threadResponse` API，监控状态变化。

8. 等状态变更为`FINISHED`后，在`detail`字段里就能看到详细的答案。

9. `detail`字段提供了在UI中看到的逐步答案。

目前Wren AI还没有提供直接下载或导出结果的功能。作为替代方案，你可以复制系统生成的原生SQL语句，然后直接在数据库中执行导出操作。

摘要

Wren AI平台让开发者或RAG/Agent应用能够轻松处理关系型数据库中的结构化数据，将用户的自然语言提示直接转化为可执行的SQL语句。UI界面里的建模菜单是至关重要的环节——它为LLM提供了额外的元数据描述和模式信息，帮助模型更好地理解你的数据库。一旦建模完成，Wren AI就像是一个智能中介，架设在数据库和用户之间。你只需要对着数据库说话，它就能把业务语言瞬间翻译成高效的SQL查询。这种前所未有的简洁性，让数据库操作真正做到了“想什么，查什么”。