# https://github.com/Agenta-AI/agenta 项目说明书 生成时间：2026-06-21 12:38:18 UTC ## 目录 - [Project Overview and System Architecture](#page-1) - [Evaluation System and Workflows](#page-2) - [Observability, Tracing, and Prompt Management](#page-3) - [Self-hosting, Database Migrations, and LLM Provider Integration](#page-4) ## Project Overview and System Architecture ### 相关页面 相关主题：[Evaluation System and Workflows](#page-2), [Observability, Tracing, and Prompt Management](#page-3), [Self-hosting, Database Migrations, and LLM Provider Integration](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [web/oss/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/oss/README.md) - [web/packages/agenta-entities/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/README.md) - [web/packages/agenta-ui/src/Editor/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-ui/src/Editor/README.md) - [web/_reference/agenta-sdk/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/_reference/agenta-sdk/README.md) - [examples/python/RAG_QA_chatbot/README.md](https://github.com/Agenta-AI/agenta/blob/main/examples/python/RAG_QA_chatbot/README.md) - [web/packages/agenta-entities/src/environment/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/environment/README.md) - [agents/skills/README.md](https://github.com/Agenta-AI/agenta/blob/main/agents/skills/README.md) - [web/oss/package.json](https://github.com/Agenta-AI/agenta/blob/main/web/oss/package.json)
# 项目概览与系统架构 ## 项目定位与核心能力 Agenta 是一个面向大语言模型（LLM）应用的全栈开发与观测平台，覆盖提示工程（prompt engineering）、评估（evaluation）、可观测性（tracing / observability）以及托管部署等关键环节。社区近期讨论集中在评估结果表格的 scenario 过滤（[#4282](https://github.com/Agenta-AI/agenta/issues/4282)）、Azure OpenAI 集成诉求（[#2153](https://github.com/Agenta-AI/agenta/issues/2153)）以及首次部署后默认凭据不可用的问题（[#2675](https://github.com/Agenta-AI/agenta/issues/2675)），这些议题共同指向平台"提示即代码 + 多人协作评估 + 一键自托管"的核心定位。 平台以 FastAPI 为后端基础，通过 Python SDK 提供调用入口，并以 Next.js 15 + React 19 构建管理控制台。前端核心交互——例如提示词编辑器——基于 [Lexical](https://lexical.dev/) 富文本与代码编辑框架，支持 JSON / YAML 语法高亮、模板变量（token）渲染、Diff 对比与表单化编辑。资料来源：[web/packages/agenta-ui/src/Editor/README.md:1-15]()。 ## 系统架构总览 Agenta 仓库采用「后端 API + 前端 Web + SDK + 示例应用」四层结构： ```mermaid flowchart LR A["Next.js 前端 Web
web/oss"] B["FastAPI 后端
api/oss + api/ee"] C["TypeScript SDK
web/_reference/agenta-sdk"] D[("Postgres / Alembic")] E[("向量库 / 第三方 LLM")] F["examples/python/*"] G["Python SDK
agenta_client"] A --> B A --> C B --> D B --> E F --> B G --> B ``` 后端同时提供 OSS 版与 EE 版入口，前端 `web/oss` 通过模块化（modules）+ Jotai 原子化状态分层组织代码，跨模块共享的 hooks、组件与类型逐级上提，从而平衡"模块自治"与"全局复用"。资料来源：[web/oss/README.md:1-40]()。 ## 核心模块构成 ### 实体（Entity）层 `@agenta/entities` 包集中实现工作流（workflow）、追踪（trace）、环境（environment）、测试集（testset）、测试用例（testcase）等实体的"molecule"控制器，统一暴露 `atoms / actions / get / set / useController / cleanup` 接口。配套的 `@agenta/entity-ui` 提供模态、选择器与下钻视图等 UI 组件。环境实体额外抽象了 Git 三层模型 `Environment → EnvironmentVariant → EnvironmentRevision`，并通过 `SimpleEnvironment` API 在前端隐藏 git 细节，支持 `is_guarded` 守门提交与基于 `delta`（set / remove）的增量变更。资料来源：[web/packages/agenta-entities/README.md:1-50]()、[web/packages/agenta-entities/src/environment/README.md:1-30]()。 ### 评估与可观测性 评估结果支持以 scenario 维度组织表格，社区在 [#4282](https://github.com/Agenta-AI/agenta/issues/4282) 中要求新增列内过滤以便横向对比多次运行。平台同步通过 `tracing` 模块聚合 span、trace、session 与人工标注（annotation），形成评估—观测—反馈闭环。资料来源：[web/_reference/agenta-sdk/README.md:1-30]()。 ### 编辑器与富交互 `@agenta/ui` 中的 `Editor` 组件支持 `codeOnly`、`showToolbar`、`enableTokens`、`templateFormat` 等十余项配置，可结合 JSON Schema 校验实现"prompt 即代码"的编辑体验，并通过 `onPropertyClick` 与下钻视图（DrillInView）联动。资料来源：[web/packages/agenta-ui/src/Editor/README.md:15-50]()。 ## 部署与开发工作流 仓库提供 `hosting/docker-compose/oss/` 下的 Compose 文件用于一键部署；社区案例（[#2675](https://github.com/Agenta-AI/agenta/issues/2675)）显示 `agenta-oss-gh-alembic-1` 容器迁移失败会导致 Web 容器无法初始化，建议首次启动后立即修改默认账号密码并确认数据库迁移日志。`examples/python/` 目录提供 RAG 问答等端到端样例（如 `RAG_QA_chatbot`、`rag-docs-qa`），使用 Qdrant、Cohere 与 OpenAI 演示"文档摄取 → 语义检索 → 流式回答 → 标注"全链路。资料来源：[examples/python/RAG_QA_chatbot/README.md:1-20]()、[examples/python/custom_workflows/rag-docs-qa/README.md:1-30]()。 在代码治理方面，`agents/skills/` 定义了 `scan-codebase / test-codebase / sync-findings / triage-findings / resolve-findings` 五段式技能工作流，统一处理 GitHub 评论、文档与测试三方证据，确保 OSS/EE 收敛评估与 schema parity 设计（v0.104.0 引入）等关键变更可追溯。资料来源：[agents/skills/README.md:1-30]()。 ## See Also - Editor Module - Environment Entity - Agenta SDK Reference - Docker Compose 部署指南 --- ## Evaluation System and Workflows ### 相关页面 相关主题：[Project Overview and System Architecture](#page-1), [Observability, Tracing, and Prompt Management](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [web/packages/agenta-entities/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/README.md) - [web/packages/agenta-entities/src/runnable/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/runnable/README.md) - [web/packages/agenta-entities/src/testset/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/testset/README.md) - [web/packages/agenta-entities/src/testcase/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/testcase/README.md) - [web/packages/agenta-entities/src/environment/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/environment/README.md) - [web/_reference/agenta-sdk/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/_reference/agenta-sdk/README.md) - [examples/python/RAG_QA_chatbot/README.md](https://github.com/Agenta-AI/agenta/blob/main/examples/python/RAG_QA_chatbot/README.md) - [web/oss/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/oss/README.md)
# 评估系统与工作流 ## 概述 Agenta 的评估系统是一套用于对大语言模型（LLM）应用进行打分、对比与回放的前端数据层与工作流编排框架。它在 `web/packages/agenta-entities` 包内以 **molecule（分子）架构** 组织，将"应用修订（app revision）"、"评估器修订（evaluator revision）"、"测试集（testset）"、"测试用例（testcase）"、"环境（environment）"等核心实体统一抽象，并通过 `runnable`、`evaluationQueue`、`evaluationRun` 等专用模块提供执行、排队、结果回放能力。 评估系统的核心职责包括： - **版本化执行单元**：每一个被评估的对象都是一个 `runnable`（可执行实体），涵盖应用修订与评估器修订两类。`资料来源：[web/packages/agenta-entities/src/runnable/README.md:1-15]()` - **声明式状态管理**：每个实体遵循一致的 controller 模式，提供 `atoms`（订阅）、`actions`（写入）、`useController`（React 钩子）与 `cleanup`（资源回收）。`资料来源：[web/packages/agenta-entities/README.md:30-50]()` - **能力命名空间**：对于可执行与可加载实体，额外暴露 `runnable.*` 与 `loadable.*` 子命名空间，承载输入/输出端口、字段映射、调用桥接等职责。`资料来源：[web/packages/agenta-entities/README.md:50-58]()` ## 核心实体与控制器模式 ### 实体控制器 API Agenta 前端在 `agenta-entities` 包内为每类实体提供统一的访问形态： | 命名空间 | 用途 | |----------|------| | `entity.atoms.*` | 通过 Jotai atom family 进行响应式订阅 | | `entity.actions.*` | 写入型原子，配合 `set()` 进行组合 | | `entity.get.*` / `entity.set.*` | 命令式读写，供回调函数使用 | | `entity.useController` | React 钩子，合并原子与派发 | | `entity.cleanup.*` | 卸载与内存回收 | `资料来源：[web/packages/agenta-entities/README.md:36-58]()` ### 可执行实体（Runnable） `runnable` 模块统一了"可被调用并产生输出"的实体，是评估系统中最核心的抽象。运行时的输入端口（`inputPorts`）、输出端口（`outputPorts`）以及运行时配置（`configuration`）都通过 `workflowMolecule` 的选择器暴露给 UI 层： ```typescript const data = useAtomValue(workflowMolecule.selectors.data(revisionId)) const inputPorts = useAtomValue(workflowMolecule.selectors.inputPorts(revisionId)) const outputPorts = useAtomValue(workflowMolecule.selectors.outputPorts(revisionId)) ``` `资料来源：[web/packages/agenta-entities/src/runnable/README.md:9-25]()` 模块内部按 `types.ts`（共享类型与端口定义）、状态管理与选择器等分层组织，明确划分职责。`资料来源：[web/packages/agenta-entities/src/runnable/README.md:30-45]()` ### 测试集与测试用例 评估的输入来源由 **testset / revision / testcase** 三级关系描述：`testset` 拥有多个 `revision`，每个 `revision` 可挂载一批 `testcase`。`资料来源：[web/packages/agenta-entities/src/testset/README.md:1-20]()`、`资料来源：[web/packages/agenta-entities/README.md:8-22]()` `testcase` 模块额外提供 `testcaseDataController`，作为分页表格的数据源抽象，支撑 `InfiniteVirtualTable` 这类大型结果集的渲染。`资料来源：[web/packages/agenta-entities/src/testcase/README.md:1-30]()` ### 环境与部署 环境是评估执行的载体。后端使用三层的 git 模型（`Environment → EnvironmentVariant → EnvironmentRevision`），前端通过 SimpleEnvironment API 将其扁平化。修订提交支持"全量快照（`data`）"与"增量操作（`delta`，包含 `set`/`remove`）"两种模式。被守卫（`is_guarded: true`）的环境必须在部署前显式批准。`资料来源：[web/packages/agenta-entities/src/environment/README.md:1-30]()` ```mermaid flowchart LR TS[Testset] --> RV[Revision] RV --> TC[Testcase 列表] TC --> RN[runnable.workflowMolecule] RN --> EV[Environment Revision] EV --> Q[evaluationQueue] Q --> RUN[evaluationRun] RUN --> RES[结果 / 打分 / 回放] ``` ## 数据流与状态管理 ### Server → Atom 链路 所有实体均采用一致的取数路径：HTTP 响应 → TanStack Query → Jotai atoms。`资料来源：[web/packages/agenta-entities/README.md:55-65]()`。这意味着评估结果一旦从后端拉回，前端组件即可通过 `useAtomValue` 订阅，无需手动维护缓存同步逻辑。 ### 模块化目录与状态归属 `web/oss` 工程将功能划分为"模块（module）"，每个模块自包含组件、钩子与静态资源。状态归属遵循三条原则： - 仅在单个组件使用的状态保留为局部 `useState`； - 模块内多个组件共享的状态下沉到模块 `store/`（Jotai atoms / Context）； - 跨模块共享的状态提升到根 `store/`。`资料来源：[web/oss/README.md:1-40]()` 这一约定直接影响评估页面：当筛选、对比、回放等状态仅用于评估模块时，应放置于模块内 store；如需跨页签保持选中态，则提升到全局。社区在 [#4282](https://github.com/Agenta-AI/agenta/issues/4282) 中提出的"评估结果表筛选"诉求，正是建立在 `testcaseDataController` 提供的分页数据源之上。 ### 评估队列与执行协调 `simpleQueue`、`evaluationQueue`、`queue` 与 `evaluationRun` 四个模块共同承担评估任务的编排： - `simpleQueue` 提供最小可用的队列原子； - `evaluationQueue` 在其之上叠加评估场景所需的元数据； - `queue` 作为统一队列控制器整合两者； - `evaluationRun` 记录每一次评估运行的快照与结果。 `资料来源：[web/packages/agenta-entities/README.md:18-28]()` ## 与 SDK、可观测性的集成 `agenta-sdk` 通过 `annotations` 命名空间提供基于 trace 的人工反馈与查询能力，使评估器可针对任意 `trace`/`span` 写入或读取标注；`tracing` 命名空间则暴露 `querySpans`、`queryTraces`、`queryByApplication` 等接口用于评估结果回溯。`资料来源：[web/_reference/agenta-sdk/README.md:1-40]()` 在 `examples/python/RAG_QA_chatbot` 中，FastAPI 后端通过 Agenta Cloud 完成完整追踪（tracing），进而被用于评估与调试：响应流式输出、引用回显、链路可观测均通过这一通道闭环。`资料来源：[examples/python/RAG_QA_chatbot/README.md:1-30]()` 需要注意的是，评估器修订通常通过 LiteLLM 调用上游模型，社区在 [#2153](https://github.com/Agenta-AI/agenta/issues/2153) 中提出的 Azure OpenAI 集成诉求，本质上需要在 SDK 与评估器层补齐相应的 provider 适配。在 [#637](https://github.com/Agenta-AI/agenta/issues/637) 提出的 Pydantic 升级也直接关系到评估器输入/输出 schema 的校验能力。 ## 常见问题与失败模式 - **登录与部署失败**：使用 `docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh --profile with-web up -d` 部署后，`agenta-oss-gh-alembic-1` 容器可能因迁移失败无法启动（见 [#2675](https://github.com/Agenta-AI/agenta/issues/2675)），导致评估相关数据库表无法创建。 - **结果筛选缺口**：评估结果表的列筛选尚未提供（见 [#4282](https://github.com/Agenta-AI/agenta/issues/4282)），需要结合 `testcaseDataController` 的分页能力手动实现。 - **依赖膨胀**：`agenta-web` 中存在未使用的依赖与错位的 `type dependencies`（见 [#1712](https://github.com/Agenta-AI/agenta/issues/1712)），可能影响评估页面的构建产物尺寸与启动速度。 ## 参见 - [Environment Entity](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/environment/README.md) - [Testset Entity](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/testset/README.md) - [Testcase Entity](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/testcase/README.md) - [Runnable Module](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/runnable/README.md) - [Agenta SDK Reference](https://github.com/Agenta-AI/agenta/blob/main/web/_reference/agenta-sdk/README.md) - [OSS Web Module Conventions](https://github.com/Agenta-AI/agenta/blob/main/web/oss/README.md) --- ## Observability, Tracing, and Prompt Management ### 相关页面 相关主题：[Project Overview and System Architecture](#page-1), [Evaluation System and Workflows](#page-2)
相关源码文件 以下源码文件用于生成本页说明： - [examples/python/RAG_QA_chatbot/README.md](https://github.com/Agenta-AI/agenta/blob/main/examples/python/RAG_QA_chatbot/README.md) - [examples/node/observability-vercel-ai/README.md](https://github.com/Agenta-AI/agenta/blob/main/examples/node/observability-vercel-ai/README.md) - [web/_reference/agenta-sdk/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/_reference/agenta-sdk/README.md) - [web/_reference/agenta-sdk-ai/src/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/_reference/agenta-sdk-ai/src/README.md) - [web/packages/agenta-entities/src/trace/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/trace/README.md) - [web/packages/agenta-entities/src/environment/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/environment/README.md) - [web/packages/agenta-entities/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/README.md) - [web/oss/src/lib/onboarding/widget/config.ts](https://github.com/Agenta-AI/agenta/blob/main/web/oss/src/lib/onboarding/widget/config.ts)
# 可观测性、追踪与提示词管理 ## 概述与目标 Agenta 平台围绕 **LLM 应用的可观测性（Observability）、追踪（Tracing）和提示词（Prompt）版本管理** 构建核心能力。Python 与 Node.js 端的官方示例均通过 OpenTelemetry（OTel）协议把 span / trace 推送到 Agenta，使后端能够统一记录每一次 LLM 调用、检索与提示词渲染过程 资料来源：[examples/node/observability-vercel-ai/README.md:30-50](https://github.com/Agenta-AI/agenta/blob/main/examples/node/observability-vercel-ai/README.md)。 前端通过 `@agenta/entities/trace` 模块读取追踪数据，并将其与提示词、应用变体绑定展示，最终在评估、调试、对比与回滚场景中复用同一份 trace 上下文 资料来源：[web/packages/agenta-entities/src/trace/README.md:1-40](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/trace/README.md)。社区中关于评估结果过滤（issue #4282）与 Azure OpenAI 集成（issue #2153）的讨论均直接依赖追踪层提供的数据上下文——若缺失 span 归因，评估对比和模型替换都难以落地。 最新发布 `v0.104.0` 完成了 OSS/EE 共用 membership 表与 schema parity 的对齐，使自部署场景下的追踪与提示词租户隔离更加稳定（参见最新发布说明）。 ## 追踪数据流与 SDK 接入 ```mermaid flowchart LR A[用户应用
SDK / OTel] --> B[OTLP Exporter] B --> C[Agenta OTLP 接入] C --> D[规范化
Normalizer / Adapter] D --> E[追踪服务
tracing/service.py] E --> F[(数据库)] F --> G[@agenta/entities/trace
前端 atom] G --> H[Trace 树 / 详情面板] ``` Node.js 端的最小接入示例：只需在 `generateText` 调用上启用 `experimental_telemetry.isEnabled = true`，SDK 便会自动创建并导出 span，无需手写 OTel 代码 资料来源：[examples/node/observability-vercel-ai/README.md:30-50](https://github.com/Agenta-AI/agenta/blob/main/examples/node/observability-vercel-ai/README.md)。Python 端的 RAG 例子在 FastAPI 后端调用 Agenta SDK，把 Qdrant 检索、提示词拼接、模型推理都纳入追踪范围 资料来源：[examples/python/RAG_QA_chatbot/README.md:1-20](https://github.com/Agenta-AI/agenta/blob/main/examples/python/RAG_QA_chatbot/README.md)。 官方 TypeScript SDK 在 `tracing` 命名空间下提供 `querySpans / queryTraces / queryByApplication / getTrace / getSpan / deleteTrace / querySessions / queryUsers / queryAnalytics` 等高级查询 资料来源：[web/_reference/agenta-sdk/README.md:1-30](https://github.com/Agenta-AI/agenta/blob/main/web/_reference/agenta-sdk/README.md)。`@agenta/sdk/ai` 在此之上进一步抽象 agent 循环与停止条件，把 `applicationSlug` 自动绑定到追踪中的 `applicationId` 资料来源：[web/_reference/agenta-sdk-ai/src/README.md:30-70](https://github.com/Agenta-AI/agenta/blob/main/web/_reference/agenta-sdk-ai/src/README.md)。 ## 前端追踪实体模块 `@agenta/entities/trace` 是 Agenta 前端处理追踪的核心 entity，遵循统一的 Entity Controller Pattern：`atoms` 提供响应式订阅，`actions` 写入原子，`get / set` 暴露命令式 API 资料来源：[web/packages/agenta-entities/README.md:40-70](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/README.md)。 模块在两个抽象层级上工作： | 层级 | 名称 | 用途 | 特性 | |------|------|------|------| | Span | `molecule` | 编辑单个 span、追踪详情面板 | 支持 draft 与 dirty 跟踪 | | Trace | `traceEntityAtomFamily` | 拉取完整 trace | 只读、自动填充 span 缓存 | 资料来源：[web/packages/agenta-entities/src/trace/README.md:50-70](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/trace/README.md)。 文件夹结构遵循 `core / api / state / utils` 的分层约定，便于在不同 entity 之间复用 selector 与类型定义 资料来源：[web/packages/agenta-entities/src/trace/README.md:10-30](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/trace/README.md)。在引导（onboarding）流程中，"Annotate traces" 与 "Create a test set from traces" 两个引导步骤都以追踪事件（`trace_annotated`、`testset_created_from_traces`）作为完成判据，进一步佐证 trace 是连接调试、评估与测试集的枢纽 资料来源：[web/oss/src/lib/onboarding/widget/config.ts:1-50](https://github.com/Agenta-AI/agenta/blob/main/web/oss/src/lib/onboarding/widget/config.ts)。 ## 提示词与环境管理 提示词以 **Environment** 实体形式存储在 Git 风格的三层版本库中：`Environment → EnvironmentVariant → EnvironmentRevision`。前端通过 **SimpleEnvironment API** 将其扁平化为单一对象，`variant_id` 与 `revision_id` 内部对 git 层透明，使前端组件无需感知底层版本控制 资料来源：[web/packages/agenta-entities/src/environment/README.md:30-70](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/environment/README.md)。 每次提交既可以是完整快照（`data`）也可以是增量 delta（`set` / `remove`），实现轻量回滚与对比。生产环境可设置 `is_guarded: true`，必须显式调用 `guardEnvironment` / `unguardEnvironment` 才能覆盖 资料来源：[web/packages/agenta-entities/src/environment/README.md:60-90](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/environment/README.md)。 关键端点（来自同源 README）：`POST /simple/environments/query`、`POST /simple/environments/`、`PUT /simple/environments/{id}`、`POST /simple/environments/{id}/archive|unarchive`、`POST /simple/environments/{id}/guard|unguard`、`POST /environments/revisions/commit`、`POST /environments/revisions/query`。 > 常见故障：自部署 OSS 时若 alembic 容器（issue #2675）未正常启动，会导致用户/membership 表漂移，进而在写入 trace 时触发外键错误。建议先用 `docker compose ps` 确认 `agenta-oss-gh-alembic-1` 处于 healthy 状态后再进行追踪写入。 ## See Also - [web/packages/agenta-entities/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/README.md) — Entity 总览与控制器模式 - [examples/python/RAG_QA_chatbot/README.md](https://github.com/Agenta-AI/agenta/blob/main/examples/python/RAG_QA_chatbot/README.md) — Python 端到端可观测性示例 - [web/_reference/agenta-sdk/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/_reference/agenta-sdk/README.md) — SDK API 索引 - [web/packages/agenta-entities/src/environment/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/environment/README.md) — Environment 实体细节 --- ## Self-hosting, Database Migrations, and LLM Provider Integration ### 相关页面 相关主题：[Project Overview and System Architecture](#page-1), [Observability, Tracing, and Prompt Management](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [api/oss/databases/postgres/migrations/runner.py](https://github.com/Agenta-AI/agenta/blob/main/api/oss/databases/postgres/migrations/runner.py) - [api/oss/databases/postgres/migrations/core/env.py](https://github.com/Agenta-AI/agenta/blob/main/api/oss/databases/postgres/migrations/core/env.py) - [api/oss/databases/postgres/migrations/core_oss/env.py](https://github.com/Agenta-AI/agenta/blob/main/api/oss/databases/postgres/migrations/core_oss/env.py) - [docs/docs/self-host/01-quick-start.mdx](https://github.com/Agenta-AI/agenta/blob/main/docs/docs/self-host/01-quick-start.mdx) - [docs/docs/self-host/02-configuration.mdx](https://github.com/Agenta-AI/agenta/blob/main/docs/docs/self-host/02-configuration.mdx) - [docs/docs/self-host/03-upgrading.mdx](https://github.com/Agenta-AI/agenta/blob/main/docs/docs/self-host/03-upgrading.mdx) - [hosting/docker-compose/oss/docker-compose.gh.yml](https://github.com/Agenta-AI/agenta/blob/main/hosting/docker-compose/oss/docker-compose.gh.yml) - [hosting/docker-compose/oss/.env.oss.gh](https://github.com/Agenta-AI/agenta/blob/main/hosting/docker-compose/oss/.env.oss.gh) - [web/packages/agenta-entities/src/secret/README.md](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/secret/README.md) - [web/packages/agenta-entities/src/secret/core/transforms.ts](https://github.com/Agenta-AI/agenta/blob/main/web/packages/agenta-entities/src/secret/core/transforms.ts)
# Self-hosting, Database Migrations, and LLM Provider Integration ## 概述 Agenta 的自托管（self-hosting）面向希望在自有基础设施上运行平台的团队，配套提供基于 Alembic 的数据库迁移以及统一的 LLM Provider 接入层。社区中两类高频问题直接对应本页主题：部署后找不到初始登录凭据——多数由 Alembic 迁移容器启动失败引起（issue #2675）；以及希望接入 Azure OpenAI 等自定义 LLM 提供方（issue #2153）。本页围绕三条主线展开：自托管快速开始与配置、Alembic 迁移机制、以及通过 Vault/Secret 实体接入 LLM Provider。 ## Self-hosting 快速开始与配置 OSS 版本通过 `docker-compose.gh.yml` 一键启动。该文件位于 [hosting/docker-compose/oss/docker-compose.gh.yml](https://github.com/Agenta-AI/agenta/blob/main/hosting/docker-compose/oss/docker-compose.gh.yml)，配套环境变量模板为 [hosting/docker-compose/oss/.env.oss.gh](https://github.com/Agenta-AI/agenta/blob/main/hosting/docker-compose/oss/.env.oss.gh)。标准启动命令如下： ```bash docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml \ --env-file hosting/docker-compose/oss/.env.oss.gh \ --profile with-web up -d ``` 启动后，平台在第一次运行时会通过 Alembic 容器自动初始化数据库模式（schema），随后才能生成默认超级管理员账户。资料来源：[docs/docs/self-host/01-quick-start.mdx:1-80]() 与 [docs/docs/self-host/02-configuration.mdx:1-120]()。 关键配置项说明如下： | 配置项 | 说明 | |--------|------| | `POSTGRES_*` | PostgreSQL 连接信息（主机、端口、库名、用户、密码） | | `REDIS_*` | Redis 缓存与队列连接信息 | | `AGENTA_AUTH_KEY` 等 `AGENTA_*` | 平台运行时鉴权与功能开关 | | `--profile with-web` | 是否同时拉起前端 Web 容器 | 升级到新版本时，应参照 [docs/docs/self-host/03-upgrading.mdx](https://github.com/Agenta-AI/agenta/blob/main/docs/docs/self-host/03-upgrading.mdx) 中的步骤重新拉取镜像并执行迁移容器。 ## 基于 Alembic 的数据库迁移 迁移容器启动失败是社区中的高频故障。issue #2675 报告 `agenta-oss-gh-alembic-1` 容器无法启动，进而无法生成初始登录凭据。Agenta 的迁移实现由三个核心模块组成： - `api/oss/databases/postgres/migrations/runner.py`：迁移入口与编排逻辑。资料来源：[api/oss/databases/postgres/migrations/runner.py:1-60]()。 - `api/oss/databases/postgres/migrations/core/env.py`：商业版（EE）数据库的环境配置。资料来源：[api/oss/databases/postgres/migrations/core/env.py:1-40]()。 - `api/oss/databases/postgres/migrations/core_oss/env.py`：OSS 版本的环境配置，与 EE 在表结构上分叉。资料来源：[api/oss/databases/postgres/migrations/core_oss/env.py:1-40]()。 迁移流程示意： ```mermaid flowchart LR A[alembic 容器启动] --> B[读取 env.py 配置] B --> C{数据库可达?} C -- 否 --> Z[容器退出: 登录失败] C -- 是 --> D[读取 alembic_version] D --> E{需要升级?} E -- 是 --> F[upgrade head] E -- 否 --> G[跳过迁移] F --> H[写入新 schema_version] H --> I[API 容器就绪] I --> J[生成初始管理员凭据] ``` 常见的迁移失败原因包括：PostgreSQL 不可达、目标 schema 已存在但 `alembic_version` 表冲突、以及 `.env.oss.gh` 中密码含未转义字符。排查时建议先执行 `docker logs agenta-oss-gh-alembic-1`，再根据报错确认是否需要手工运行 `alembic upgrade head` 对齐版本。 ## LLM Provider 集成与 Vault 实体 LLM Provider 接入由 `web/packages/agenta-entities/src/secret` 模块统一管理。该模块是基于 Jotai 的"查询+变更"轻量实现，被设计为新实体迁移到 molecule 模式的最小可用参考模板。资料来源：[web/packages/agenta-entities/src/secret/README.md:1-60]()。 核心能力包括： - **多 Provider 支持**：通过 `core/transforms.ts` 中的 `transformSecret` 与 `transformCustomProviderPayloadData` 函数，将前端表单数据序列化为后端可识别的 Secret 实体。资料来源：[web/packages/agenta-entities/src/secret/core/transforms.ts:1-80]()。 - **环境变量映射**：`getEnvNameMap` 将不同提供方（OpenAI、Azure OpenAI、自定义 Endpoint）的字段映射到对应环境变量名（如 `OPENAI_API_KEY`、`AZURE_OPENAI_API_KEY`、`OPENAI_API_BASE`）。资料来源：[web/packages/agenta-entities/src/secret/core/transforms.ts:40-90]()。 - **作用域隔离**：Secret 按 Project 隔离，并受用户认证状态约束；该设计既满足多团队协作，也避免凭据泄漏到非授权成员。 社区中关于 Azure OpenAI 集成的诉求（issue #2153）正是通过该模块的 `custom` Provider 形态实现：用户在前端填入 `api_base`、`deployment`、`api_version` 等字段后，`transformCustomProviderPayloadData` 会将其封装为运行时环境变量注入到 LLM 调用栈。 ## 常见失败模式 1. **Alembic 容器无法启动**：检查 `POSTGRES_*` 配置与 `alembic_version` 表的初始状态，参考 issue #2675 复现命令定位根因。 2. **Azure OpenAI 调用失败**：确认 `api_base` 形如 `https://.openai.azure.com/`，并选择 `custom` Provider 类型。 3. **升级后 Pydantic 兼容性告警**：项目历史中曾推动 Pydantic 升级（issue #637），升级时需同时检查 `requirements.txt` 与 Docker 基础镜像版本。 ## See Also - [Entity 架构总览](../entities/index.md) - [Environment 实体](../entities/environment.md) - [Testset 与 Testcase 实体](../entities/testset.md) --- --- ## Doramagic 踩坑日志 项目：Agenta-AI/agenta 摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。 ## 1. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/Agenta-AI/agenta | README/documentation is current enough for a first validation pass. ## 2. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/Agenta-AI/agenta | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/Agenta-AI/agenta | no_demo; severity=medium ## 4. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/Agenta-AI/agenta | no_demo; severity=medium ## 5. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/Agenta-AI/agenta | issue_or_pr_quality=unknown ## 6. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/Agenta-AI/agenta | release_recency=unknown