三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

基于Energy平台构建AI应用：从概念到实战的智能问答助手开发指南

发布时间：2026/8/9 21:25:37 三亩地 编程学习日记
基于Energy平台构建AI应用：从概念到实战的智能问答助手开发指南

最近在AI应用开发领域，一个由前OpenAI核心成员打造的新平台“Energy”引起了广泛关注。它并非一个通用的大模型，而是一个定位清晰的“AI工作平台”，旨在解决开发者在构建、部署和管理AI驱动应用时面临的工具链割裂、运维复杂等工程化难题。如果你正在为如何将大模型能力快速、稳定地集成到业务系统中而头疼，或者厌倦了在多个工具间来回切换，那么本文将为你深入解析Energy平台的核心设计理念、技术架构，并通过一个完整的实战案例，手把手带你体验从零搭建一个智能问答应用的全过程。无论你是AI应用开发的新手，还是寻求效率提升的资深工程师，都能从中获得可直接复用的代码和配置方案。

1. Energy平台：核心概念与解决的问题

在深入代码之前，我们首先要理解Energy是什么，以及它为何被需要。当前，利用大模型（如GPT系列、Claude等）构建应用，通常涉及多个环节：调用API、管理对话历史、处理文件上传、集成外部工具（Function Calling）、保障应用安全与可控等。开发者往往需要自行组合多个库（如LangChain、LlamaIndex）和基础设施（如向量数据库、缓存服务），这不仅引入复杂性，也增加了维护成本。

Energy作为一个AI工作平台，其核心目标是提供一套开箱即用、高度集成的开发环境与运行时。我们可以将其类比为“AI时代的Spring Boot”：它通过预设的最佳实践和封装好的组件，让开发者能更专注于业务逻辑，而非底层基础设施的搭建。其解决的关键问题包括：

  1. 开发环境标准化：提供统一的SDK、CLI工具和项目模板，确保团队内部开发体验一致。
  2. 应用编排可视化：将复杂的AI工作流（如检索增强生成RAG、多步骤推理）通过可视化或声明式配置进行编排，降低理解与调试门槛。
  3. 生产部署一体化：内置了从开发到测试、再到生产部署的流水线，简化了CI/CD流程。
  4. 资源与成本管理：提供对多模型API调用、令牌消耗、响应延迟等指标的监控与管理面板。

与单纯的大模型API服务商不同，Energy更侧重于“工作平台”，即它管理的是整个AI应用的生命周期，而不仅仅是模型调用这一个环节。

2. 环境准备与项目初始化

在开始实战前，我们需要准备好开发环境。Energy目前主要支持Python和JavaScript/TypeScript生态。本文将以Python为例进行演示，这是AI应用开发中最主流的语言。

2.1 基础环境要求

  • 操作系统：macOS, Linux (如Ubuntu 20.04+), 或 Windows Subsystem for Linux (WSL 2)。推荐使用Linux或macOS以获得最佳兼容性。
  • Python版本：3.9 或 3.10。建议使用pyenv或conda管理多版本Python。
  • 包管理工具：pip(最新版)。
  • 代码编辑器：VS Code (推荐) 或 PyCharm。

2.2 安装Energy CLI工具

Energy提供了一个命令行工具，用于创建、管理和部署项目。这是与平台交互的主要入口。

打开终端，执行以下命令进行安装：

# 使用pip安装energy-cli pip install energy-cli # 安装完成后，验证安装是否成功 energy --version

如果安装成功，终端会显示类似energy, version 0.8.1的版本信息。

2.3 创建你的第一个Energy项目

我们将创建一个名为my-ai-assistant的智能问答应用项目。

# 使用CLI创建新项目 energy new my-ai-assistant # 进入项目目录 cd my-ai-assistant

创建完成后，你会看到如下的项目结构：

my-ai-assistant/ ├── .energy/ # Energy平台配置文件（如项目ID、环境变量） ├── app/ # 应用核心代码目录 │ ├── __init__.py │ ├── main.py # 应用主入口文件 │ └── workflows/ # 工作流定义目录 ├── tests/ # 测试文件目录 ├── requirements.txt # Python依赖列表 ├── energy.toml # 项目声明式配置（依赖、环境变量、工作流等） └── README.md

这个结构已经遵循了Energy的最佳实践，energy.toml是项目的核心配置文件。

2.4 配置模型API密钥

Energy本身不提供大模型，而是作为中间层连接OpenAI、Anthropic等模型提供商。你需要准备相应的API密钥。

  1. 在项目根目录，复制环境变量示例文件：
    cp .energy/.env.example .energy/.env
  2. 编辑.energy/.env文件，填入你的API密钥。切记不要将此文件提交到版本控制系统！
    # .energy/.env OPENAI_API_KEY=sk-your-openai-api-key-here # ANTHROPIC_API_KEY=your-claude-api-key-here # 可以配置多个模型的密钥
    这里我们以OpenAI的GPT模型为例。请将sk-your-openai-api-key-here替换为你自己的有效API密钥。

3. 核心配置与概念拆解：energy.toml

energy.toml是Energy项目的“大脑”，它采用TOML格式，以声明式的方式定义了应用的所有组件和连接关系。理解它至关重要。

3.1 基础项目配置

打开energy.toml，我们先看最外层的配置：

# energy.toml [project] name = "my-ai-assistant" version = "0.1.0" description = "一个基于Energy平台的智能问答助手"

这部分定义了项目的基本元信息。

3.2 定义模型供应商（Providers）

providers部分声明了你的应用将使用哪些AI模型服务。

[providers.openai] type = "openai" # api_key 会自动从 .energy/.env 中的 OPENAI_API_KEY 环境变量读取 model = "gpt-4o-mini" # 指定默认使用的模型 # 你可以定义多个provider，例如Claude # [providers.anthropic] # type = "anthropic" # model = "claude-3-5-sonnet-20241022"

这里我们定义了一个名为openai的provider，类型是openai，并指定默认使用gpt-4o-mini模型。Energy会自动将环境变量中的OPENAI_API_KEY注入到这个provider的调用中。

3.3 定义工具（Tools）

tools是AI模型可以调用的外部函数。这是实现AI“行动力”的关键。例如，让AI可以查询天气、搜索数据库或调用内部API。

[tools.get_current_time] type = "function" description = "获取当前的日期和时间。当用户询问时间或日期时使用此工具。" function = "app.tools:get_current_time" # 指向Python函数 [tools.search_web] type = "function" description = "在互联网上搜索信息。当需要获取最新或未知信息时使用。" function = "app.tools:search_web"

这里定义了两个工具：get_current_time和search_web。function字段指向了具体的Python实现函数（我们稍后编写）。

3.4 定义工作流（Workflows）

workflows是应用的核心逻辑单元。一个工作流定义了从用户输入到AI响应的完整处理过程。最简单的形式是“聊天工作流”。

[workflows.chat] type = "chat" description = "主聊天对话工作流" provider = "openai" # 使用上面定义的openai provider model = "gpt-4o-mini" # 可以覆盖provider的默认模型 tools = ["get_current_time", "search_web"] # 该工作流可使用的工具列表 system_prompt = """ 你是一个乐于助人且知识渊博的AI助手。 你的目标是准确、清晰地回答用户的问题。 如果信息不足，你可以使用搜索工具来查找最新信息。 回答请尽量简洁，但确保信息完整。 """

这个名为chat的工作流，使用了openaiprovider和gpt-4o-mini模型，并赋予了它使用get_current_time和search_web两个工具的能力。system_prompt设置了AI的初始角色和指令。

4. 完整实战：构建智能问答助手

现在，我们来编写具体的代码，实现上面配置中定义的工具和工作流。

4.1 实现工具函数

在app目录下创建tools.py文件。

# app/tools.py import datetime from typing import Dict, Any import requests from energy import Tool class GetCurrentTimeTool(Tool): """获取当前时间的工具实现类。""" name = "get_current_time" description = "获取当前的日期和时间（UTC）。" def run(self) -> Dict[str, Any]: """执行工具逻辑。""" now_utc = datetime.datetime.utcnow() return { "success": True, "current_time_utc": now_utc.isoformat(), "message": f"当前UTC时间是：{now_utc.strftime('%Y-%m-%d %H:%M:%S')}" } # 注意：Energy也支持简单的函数式定义，这里展示类式定义以体现类型提示和结构。 # 对应的函数式定义如下（二选一即可）： # def get_current_time() -> Dict[str, Any]: # now_utc = datetime.datetime.utcnow() # return { # "success": True, # "current_time_utc": now_utc.isoformat(), # "message": f"当前UTC时间是：{now_utc.strftime('%Y-%m-%d %H:%M:%S')}" # }

对于搜索工具，我们需要一个更复杂的实现。这里我们使用一个模拟的搜索函数，实际项目中你可以接入Serper、Google Search API等真实服务。

# app/tools.py (续) class SearchWebTool(Tool): """模拟网络搜索工具。实际应接入真实搜索API。""" name = "search_web" description = "在互联网上搜索信息。输入应为搜索查询词。" def __init__(self): # 模拟一些预设的“知识”，代替真实网络请求 self.knowledge_base = { "Energy平台的最新版本": "Energy平台目前最新稳定版是v0.8.2，引入了工作流版本管理功能。", "Python 3.12的新特性": "Python 3.12 主要新特性包括：更友好的错误信息、性能提升、新的类型注解语法等。", "今天的天气": "根据模拟数据，今天北京天气晴朗，气温15-25摄氏度。" } def run(self, query: str) -> Dict[str, Any]: """执行搜索逻辑。 Args: query: 用户的搜索查询词。 """ # 在实际应用中，这里应该是 requests.get(...) 调用搜索API # 例如：response = requests.get(f"https://serper.dev/search?q={query}") # 模拟搜索延迟 import time time.sleep(0.5) result = self.knowledge_base.get( query, f"未找到关于 '{query}' 的精确信息。请尝试更换关键词或描述更具体的问题。" ) return { "success": True, "query": query, "result": result, "source": "simulated_web_search" }

4.2 编写应用主入口

修改app/main.py文件，创建一个简单的FastAPI应用来暴露我们的聊天工作流。

# app/main.py from fastapi import FastAPI, HTTPException from pydantic import BaseModel from energy import EnergyApp import uvicorn # 初始化Energy应用，它会自动加载 energy.toml 配置和 tools.py 中的工具 app = EnergyApp() # 创建FastAPI实例 web_app = FastAPI(title="My AI Assistant API") # 定义请求/响应模型 class ChatRequest(BaseModel): message: str workflow: str = "chat" # 默认使用我们在配置中定义的‘chat’工作流 stream: bool = False # 是否使用流式响应 class ChatResponse(BaseModel): reply: str workflow_used: str tools_called: list = [] @web_app.post("/chat", response_model=ChatResponse) async def chat_endpoint(request: ChatRequest): """处理聊天请求的API端点。""" try: # 调用Energy App执行工作流 result = await app.run_workflow( workflow_name=request.workflow, user_input=request.message, stream=request.stream ) # 从结果中提取信息 # result 是一个包含 messages, metadata 等的复杂对象 # 这里简化处理，取最后一条AI消息作为回复 ai_messages = [msg for msg in result.messages if msg.role == "assistant"] final_reply = ai_messages[-1].content if ai_messages else "抱歉，我没有生成回复。" # 提取被调用过的工具信息（元数据中通常包含） tools_called = result.metadata.get("tools_called", []) if hasattr(result, 'metadata') else [] return ChatResponse( reply=final_reply, workflow_used=request.workflow, tools_called=tools_called ) except Exception as e: raise HTTPException(status_code=500, detail=f"工作流执行失败: {str(e)}") @web_app.get("/health") async def health_check(): """健康检查端点。""" return {"status": "healthy", "service": "my-ai-assistant"} if __name__ == "__main__": # 本地开发运行 uvicorn.run(web_app, host="0.0.0.0", port=8000)

4.3 安装项目依赖

Energy CLI在创建项目时可能已经生成了requirements.txt，我们需要确保所有依赖已安装。

# 在项目根目录下执行 pip install -r requirements.txt

如果requirements.txt内容不全，你可能需要手动安装核心包：

pip install fastapi uvicorn pydantic requests # energy-cli 已经在第一步安装过了

4.4 运行与验证

一切就绪，现在启动我们的AI助手服务。

  1. 启动服务：

    cd my-ai-assistant python -m app.main

    终端会显示类似Uvicorn running on http://0.0.0.0:8000的信息。

  2. 测试API： 打开另一个终端，使用curl或Postman进行测试。

    # 测试健康检查 curl http://localhost:8000/health # 测试聊天接口，询问时间（会触发工具调用） curl -X POST http://localhost:8000/chat \ -H "Content-Type: application/json" \ -d '{"message": "现在几点了？"}' # 测试聊天接口，询问知识类问题（可能触发搜索） curl -X POST http://localhost:8000/chat \ -H "Content-Type: application/json" \ -d '{"message": "Energy平台最新版本是什么？"}'

  3. 查看结果： 对于“现在几点了？”的请求，响应中tools_called字段应该包含get_current_time，并且reply会给出包含当前时间的回答。 对于“Energy平台最新版本是什么？”的请求，响应会显示我们模拟搜索工具返回的结果：“Energy平台目前最新稳定版是v0.8.2...”。

4.5 使用Energy Dashboard（可选）

Energy通常提供一个本地或云端的仪表盘，用于可视化管理和监控工作流。在开发模式下，运行以下命令可能会启动一个本地管理界面：

energy dashboard

你可以在浏览器中打开提示的地址（如http://localhost:3000），查看工作流的历史运行记录、工具调用情况、令牌消耗等，这对于调试复杂工作流非常有帮助。

5. 常见问题与排查思路

在开发和部署Energy应用时，你可能会遇到以下典型问题。

问题现象可能原因排查步骤与解决方案
运行energy命令提示“command not found”1.pip install未全局安装或路径未加入系统PATH。
2. 在虚拟环境中安装但未激活。		1. 尝试使用python -m energy代替energy。
2. 确认使用的终端是否激活了正确的Python虚拟环境。
3. 重新安装：pip install --user energy-cli并重启终端。
启动应用时报错，提示API密钥无效1..energy/.env文件未创建或密钥填写错误。
2. 环境变量名与energy.toml中配置不匹配。
3. API密钥本身已过期或额度不足。		1. 检查.energy/.env文件是否存在且内容正确。
2. 确认energy.toml中provider的type与.env中的变量名前缀匹配（如openai对应OPENAI_API_KEY）。
3. 前往对应的AI服务商后台检查API密钥状态和余额。
工具（Tool）调用失败，AI回复“我无法执行该操作”1. 工具函数定义与energy.toml中的function路径不匹配。
2. 工具函数存在语法错误或运行时异常。
3. 未在工作流（workflow）的tools列表中声明该工具。		1. 仔细核对energy.toml中function字段的导入路径（如app.tools:get_current_time）是否指向真实的模块和函数。
2. 单独运行工具函数，确保其能正常工作。
3. 检查对应工作流的tools列表是否包含了该工具的名称。
应用响应速度慢1. 大模型API本身响应慢。
2. 自定义工具函数执行效率低（如网络请求、复杂计算）。
3. 工作流逻辑过于复杂，多次串行调用模型。		1. 尝试更换模型（如从gpt-4换为gpt-4o-mini）。
2. 为工具函数添加缓存、优化算法或使用异步请求。
3. 审查工作流设计，看是否可并行化某些步骤，或使用Energy提供的缓存机制。
部署到生产环境后配置不生效1. 生产环境缺少必要的环境变量。
2.energy.toml文件在构建过程中未被包含。
3. 生产环境与开发环境的Energy版本不一致。		1. 确保在服务器或容器环境（如Dockerfile、K8s Secret）中正确设置了所有API密钥等环境变量。
2. 检查项目的打包脚本（如Dockerfile的COPY指令）是否包含了.energy目录和energy.toml。
3. 在requirements.txt或Dockerfile中固定energy-cli的版本。

6. 最佳实践与工程建议

将Energy用于实际项目时，遵循以下实践能提升应用的稳定性、可维护性和安全性。

6.1 配置管理

  • 环境隔离：为开发、测试、生产环境创建不同的.energy/.env.development,.energy/.env.production文件，并通过ENERGY_ENV环境变量切换。在energy.toml中可以使用变量引用，如api_key = "${OPENAI_API_KEY}"。
  • 密钥安全：绝对不要将.env文件提交到Git。使用.gitignore确保其被忽略。在生产环境中，使用云服务商提供的密钥管理服务（如AWS Secrets Manager, GCP Secret Manager, Azure Key Vault）。
  • 配置版本化：将energy.toml纳入版本控制。它是应用的核心声明，其变更应该被代码审查。

6.2 工作流设计

  • 单一职责：每个工作流应专注于完成一个明确的业务目标（如“处理客服问答”、“生成周报摘要”）。避免创建庞大、多功能的“上帝工作流”。
  • 充分利用系统提示词（System Prompt）：精心设计system_prompt是控制AI行为最有效的方式。明确角色、规则、输出格式和禁忌。
  • 工具设计规范：
    • 为工具函数提供清晰、准确的description，这直接影响大模型是否及如何调用它。
    • 工具函数的输入参数应尽量简单（最好是基本类型），输出应结构化和标准化。
    • 在工具函数内部做好充分的错误处理和日志记录，返回明确的错误信息供AI模型理解。

6.3 代码结构与测试

  • 模块化工具：将工具函数按领域分类到不同的Python模块中（如weather_tools.py,database_tools.py），而不是全部堆在tools.py里。
  • 编写单元测试：为你的工具函数编写单元测试，确保其逻辑正确。Energy应用本身（工作流）的测试可能更偏向集成测试，可以使用Energy SDK提供的测试工具来模拟模型调用。
  • 日志与可观测性：在app/main.py和应用代码中集成结构化日志（如使用structlog或loggingJSON格式）。记录关键事件：用户请求、工作流开始/结束、工具调用详情、模型消耗的令牌数、错误信息等。这便于监控和调试。

6.4 生产部署与运维

  • 使用官方Runtime或容器化：Energy可能提供官方的托管Runtime或Docker镜像，这是最省心的部署方式。如果自行部署，确保将FastAPI应用（如使用Gunicorn+Uvicorn）正确容器化。
  • 设置速率限制和熔断：在API网关或应用层（如使用FastAPI的slowapi中间件）对/chat等端点添加速率限制，防止滥用。对模型API的调用实现熔断机制，防止因上游服务不稳定导致自身服务雪崩。
  • 监控与告警：监控关键指标：API响应延迟、错误率、模型令牌消耗成本、工具调用成功率。设置告警，当错误率飙升或成本异常时及时通知。
  • 成本控制：在energy.toml中可以为工作流设置预算或最大令牌数限制。定期审查日志，分析高成本的工作流和查询，进行优化。

7. 总结与进阶方向

通过本文的实战，我们完成了从零开始使用Energy平台构建一个具备工具调用能力的智能问答助手的全过程。我们了解了Energy的核心概念（Providers, Tools, Workflows），掌握了通过energy.toml进行声明式配置的方法，并实现了具体的工具函数和Web API。

Energy的价值在于它提供了一套高层次的抽象和集成化的工具链，将开发者从粘合各种AI组件的繁琐工作中解放出来。它的设计理念与Spring Boot之于Java后端开发类似，旨在提升AI应用开发的标准化程度和工程效率。

为了进一步深化学习，你可以尝试以下方向：

  1. 探索复杂工作流：实现一个多步骤的RAG（检索增强生成）工作流，集成向量数据库（如Chroma, Pinecone），让AI能够基于你提供的私有文档回答问题。
  2. 接入更多模型：在energy.toml中配置Anthropic Claude、Google Gemini或开源的本地模型（通过Ollama），并在不同工作流中灵活选用。
  3. 实现更复杂的工具：将工具连接到真实的内部业务系统，如CRM、ERP数据库，或外部API如发送邮件、生成图表。
  4. 深入研究Energy高级特性：了解其版本管理、A/B测试、基于评估的自动化工作流优化等功能，这些是构建可维护、可演进的生产级AI应用的关键。

AI应用开发正处于从“玩具”到“工具”的关键阶段，像Energy这样的平台正在努力填补其中的工程化鸿沟。希望本文能成为你探索这一领域的实用起点，祝你构建出强大而可靠的AI应用。如果在实践中遇到具体问题，欢迎在评论区交流探讨。

编程学习 学习日记 实战经验
← 返回列表