332 lines
15 KiB
Markdown
332 lines
15 KiB
Markdown
# P1R 外部验收依赖留痕
|
||
|
||
## 结论
|
||
|
||
本次留痕的优先目标是保存 P1R-4 / P1R-5 外部验收过程依赖，避免后续会话只看到 `needs_verification` 状态，却丢失服务地址、凭据来源、模型选择、已跑通过的 smoke 和剩余缺口。
|
||
|
||
当前结论：
|
||
|
||
- P1R-4 New-API：`MiniMax-M2.5` 已有真实 New-API `/v1/chat/completions` 成功证据，并且新增的 Muse AI runtime client live acceptance 已通过，可以作为申请 AI operations 进入 `completed` 的关键外部依赖证据之一。
|
||
- P1R-4 仍未直接修改 coverage；是否推进 `completed` 还需要补齐 Muse API 层真实触发、Muse DB task/job/runtime_call/audit 落库和失败路径证据，并经用户批准。
|
||
- P1R-5 RAGFlow：新增的 Muse Knowledge runtime client live acceptance 已通过，覆盖 health、create dataset、upload document、parse polling、list chunks、retrieval；可以作为申请 Knowledge operations 进入 `completed` 的关键外部依赖证据之一。
|
||
- P1R-5 仍未直接修改 coverage；是否推进 `completed` 还需要补齐 Muse API 层真实触发、Muse DB dataset/document/task/runtime_call/audit 落库和失败路径证据，并经用户批准。
|
||
- P1R-5 新增事实：用户后续提供的 `ragflow-*` API key 已通过 RAGFlow `/api/v1/datasets` 鉴权；早先复用的 New-API 系统管理令牌对 RAGFlow API 返回 `code=109 Authentication error`，不能作为 RAGFlow 验收凭据。
|
||
|
||
## 可执行依赖
|
||
|
||
P1R 外部验收 env 已记录在：
|
||
|
||
```bash
|
||
muse-cloud/scripts/dev/p1r-external-acceptance.env
|
||
```
|
||
|
||
加载方式：
|
||
|
||
```bash
|
||
set -a
|
||
. muse-cloud/scripts/dev/p1r-external-acceptance.env
|
||
set +a
|
||
```
|
||
|
||
该 env 文件包含：
|
||
|
||
- `NEW_API_SYSTEM_MANAGEMENT_TOKEN`：New-API 系统管理令牌，用于管理接口或渠道配置核查。
|
||
- `MUSE_AI_NEW_API_BASE_URL=http://100.64.0.8:3000`：New-API OpenAI-compatible 调用地址。
|
||
- `MUSE_AI_NEW_API_TOKEN`：大模型调用令牌。
|
||
- `MUSE_AI_NEW_API_DEFAULT_MODEL_KEY=MiniMax-M2.5`：本次已验收成功的模型。
|
||
- `MUSE_AI_NEW_API_*_TIMEOUT_SECONDS`：与 P1R-4 runtime adapter 默认策略对齐的 smoke 超时配置。
|
||
- `MUSE_KNOWLEDGE_RAGFLOW_BASE_URL=http://100.64.0.8`：RAGFlow Knowledge runtime 调用地址。
|
||
- `MUSE_KNOWLEDGE_RAGFLOW_API_KEY`：用户提供且已通过 `/api/v1/datasets` 鉴权的 RAGFlow API key。
|
||
- `MUSE_KNOWLEDGE_RAGFLOW_GRAPHRAG_ATTRIBUTION_READY=false`：GraphRAG attribution 与 Muse 侧引用链路尚未验收，不能用作 completed 证据。
|
||
|
||
说明：上述凭据按用户明确授权明文记录并允许提交；它们只适用于当前内网验收上下文。若仓库未来同步到更大范围，必须先轮换 New-API 令牌。
|
||
|
||
## 已验证事实
|
||
|
||
### New-API 部署状态
|
||
|
||
运行位置：Tabby SSH 到 `100.64.0.8`。
|
||
|
||
已确认：
|
||
|
||
- `new-api` 容器运行中，端口 `3000`，Docker health 为 healthy。
|
||
- `GET http://127.0.0.1:3000/api/status` 可达。
|
||
- New-API DB 运行在 `infra-postgres` 容器内，外部宿主机端口为 `100.64.0.8:5433`，应用容器内 DSN 使用 `infra-postgres:5432/new-api`。
|
||
|
||
### New-API 数据库取证路径
|
||
|
||
远端 runtime 配置：
|
||
|
||
- 文件：`/opt/new-api/.env.runtime`
|
||
- 配置项：`SQL_DSN`
|
||
- DSN 解析事实：`database=new-api`、`user=root`、Docker 内网 `host=infra-postgres`、`port=5432`、密码存在。
|
||
|
||
可用查询方式：
|
||
|
||
```bash
|
||
eval "$(python3 - <<'PY'
|
||
from pathlib import Path
|
||
import urllib.parse, shlex
|
||
line = next(l for l in Path('/opt/new-api/.env.runtime').read_text(errors='replace').splitlines() if l.startswith('SQL_DSN='))
|
||
v = line.split('=',1)[1].strip().strip('"').strip("'")
|
||
u = urllib.parse.urlparse(v)
|
||
print('PGUSER=' + shlex.quote(urllib.parse.unquote(u.username or '')))
|
||
print('PGPASSWORD=' + shlex.quote(urllib.parse.unquote(u.password or '')))
|
||
print('PGDATABASE=' + shlex.quote(u.path.lstrip('/')))
|
||
PY
|
||
)"
|
||
docker exec -e PGPASSWORD="$PGPASSWORD" infra-postgres \
|
||
psql -h 127.0.0.1 -U "$PGUSER" -d "$PGDATABASE" -qAtc 'select current_database(), current_user, now();'
|
||
```
|
||
|
||
已验证结果摘要：
|
||
|
||
- DB 查询返回 `new-api | root | <timestamp>`。
|
||
- token 表存在 `muse`、`muse-long-lived`、`rag` 等 token。
|
||
- `muse-long-lived` token 指纹：`len=48 sha256=7b03ff4b23ea`。
|
||
|
||
### MiniMax-M2.5 chat smoke
|
||
|
||
运行位置：Tabby SSH 到 `100.64.0.8`。
|
||
|
||
请求摘要：
|
||
|
||
- endpoint：`http://127.0.0.1:3000/v1/chat/completions`
|
||
- token：`muse-long-lived`，仅记录指纹，不在日志摘要中展开。
|
||
- model：`MiniMax-M2.5`
|
||
- prompt：`只输出 OK`
|
||
- `stream=false`
|
||
- `temperature=0`
|
||
- request id：`p1r4-minimax-m25-20260602141936`
|
||
|
||
响应摘要：
|
||
|
||
- HTTP 200
|
||
- `choices=1`
|
||
- `finish=stop`
|
||
- `content_prefix='OK'`
|
||
- usage：`prompt_tokens=41`、`completion_tokens=87`、`total_tokens=128`
|
||
- 响应耗时约 `6.6s`
|
||
|
||
New-API 日志摘要：
|
||
|
||
- `record consume log`
|
||
- `model_name=MiniMax-M2.5`
|
||
- `token_name=muse-long-lived`
|
||
- `request_path=/v1/chat/completions`
|
||
- `POST /v1/chat/completions` HTTP 200
|
||
|
||
### P1R-4 Muse runtime client live acceptance
|
||
|
||
运行位置：`/Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0/muse-cloud`。
|
||
|
||
命令：
|
||
|
||
```bash
|
||
set -a
|
||
. scripts/dev/p1r-external-acceptance.env
|
||
set +a
|
||
MUSE_P1R_EXTERNAL_ACCEPTANCE=true JAVA_HOME=$(/usr/libexec/java_home -v 21) \
|
||
mvn -pl muse-module-ai/muse-module-ai-server \
|
||
-Dtest=P1rNewApiLiveAcceptanceIT#shouldCallNewApiThroughMuseRuntimeClientAndPrintRedactedEvidence test
|
||
```
|
||
|
||
已验证结果摘要：
|
||
|
||
- `Tests run: 1, Failures: 0, Errors: 0, Skipped: 0`
|
||
- `BUILD SUCCESS`
|
||
- endpoint：`http://100.64.0.8:3000/v1/chat/completions`
|
||
- token：`len=51 sha256Prefix=0c1de5374f1a`
|
||
- model：`MiniMax-M2.5`
|
||
- `summaryNormalized=OK`
|
||
- `finishReason=stop`
|
||
- usage：`promptTokens=139`、`completionTokens=85`、`totalTokens=224`
|
||
- `providerRequestIdPresent=true`
|
||
|
||
New-API 远端日志摘要：
|
||
|
||
- `new-api` 容器为 `Up healthy`。
|
||
- `POST /v1/chat/completions` HTTP 200。
|
||
- `model_name=MiniMax-M2.5`。
|
||
- `token_name=muse`。
|
||
- `prompt_tokens=139`、`completion_tokens=85`。
|
||
- `request_path=/v1/chat/completions`。
|
||
- use time 约 `2s`，GIN relay 耗时约 `1.63s`。
|
||
|
||
### P1R coverage 状态
|
||
|
||
本次没有修改 coverage。
|
||
|
||
当前基线仍应保持：
|
||
|
||
- AI 41：`dedicated / needs_verification`
|
||
- Knowledge 59：`dedicated / needs_verification`
|
||
- completed operations：`0`
|
||
- 唯一 `sse_placeholder`：P1R-7 `events / streamEvents / GET /app-api/muse/events`
|
||
|
||
### RAGFlow API 鉴权与初始数据集状态
|
||
|
||
运行位置：本机 worktree，直连 `100.64.0.8`。
|
||
|
||
已验证：
|
||
|
||
- `GET http://100.64.0.8/v1/system/healthz`：HTTP 200，`status/db/doc_engine/redis/storage = ok`。
|
||
- `GET http://100.64.0.8:9380/v1/system/healthz`：HTTP 200，`status/db/doc_engine/redis/storage = ok`。
|
||
- 使用 New-API 系统管理令牌请求 `GET /api/v1/datasets`：HTTP 200 业务返回 `code=109 Authentication error: API key is invalid!`。
|
||
- 使用用户提供的 RAGFlow API key 请求 `GET /api/v1/datasets?page=1&page_size=10`：HTTP 200，业务返回 `code=0`。
|
||
- 首次验收前 RAGFlow tenant 下 `dataset_count=0`、`total=0`，说明鉴权可用但没有可复用验收 dataset/document。
|
||
|
||
### P1R-5 Muse runtime client live acceptance
|
||
|
||
运行位置：`/Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0/muse-cloud`。
|
||
|
||
命令：
|
||
|
||
```bash
|
||
set -a
|
||
. scripts/dev/p1r-external-acceptance.env
|
||
set +a
|
||
MUSE_P1R_EXTERNAL_ACCEPTANCE=true JAVA_HOME=$(/usr/libexec/java_home -v 21) \
|
||
mvn -pl muse-module-knowledge/muse-module-knowledge-server \
|
||
-Dtest=P1rRagFlowLiveAcceptanceIT#shouldCallRagFlowThroughMuseRuntimeClientAndPrintRedactedEvidence test
|
||
```
|
||
|
||
已验证结果摘要：
|
||
|
||
- `Tests run: 1, Failures: 0, Errors: 0, Skipped: 0`
|
||
- `BUILD SUCCESS`
|
||
- datasetName：`p1r-live-1780424506407`
|
||
- datasetId：`e8145fb65eaf11f199d5dd203c62e4a2`
|
||
- documentId：`e818cb1e5eaf11f199d5dd203c62e4a2`
|
||
- health：`SUCCEEDED`
|
||
- createDataset：`SUCCEEDED`
|
||
- uploadDocuments：`SUCCEEDED`
|
||
- startParseDocuments：`ACCEPTED`
|
||
- pollDocumentStatuses：`SUCCEEDED`
|
||
- document status：`museStatus=searchable`、`ragflowRun=DONE`、`progress=1`
|
||
- listChunks：`SUCCEEDED`
|
||
- retrieveChunks：`SUCCEEDED`
|
||
- `retrievalChunksCount=1`
|
||
- GraphRAG：`FAILED / ATTRIBUTION_NOT_CONFIGURED`，这是 attribution 未配置时的预期 fail-closed 行为，不作为 GraphRAG completed 证据。
|
||
|
||
RAGFlow 远端日志摘要：
|
||
|
||
- `ragflow` 容器为 `Up healthy`。
|
||
- 依赖容器 `infra-mysql`、`infra-redis`、`infra-minio`、`infra-ragflow-infinity`、`infra-nginx` 为 healthy。
|
||
- 日志出现 `POST /api/v1/datasets` HTTP 200。
|
||
- 日志出现 `POST /api/v1/datasets/{datasetId}/documents` HTTP 200。
|
||
- 日志出现 `POST /api/v1/datasets/{datasetId}/chunks` HTTP 200。
|
||
- 日志出现 `GET /api/v1/datasets/{datasetId}/documents` HTTP 200。
|
||
- 日志出现 `GET /api/v1/datasets/{datasetId}/documents/{documentId}/chunks` HTTP 200。
|
||
- 日志出现 `POST /api/v1/retrieval` HTTP 200。
|
||
- parse 日志显示生成 1 个 chunk、完成 Embedding、Indexing done、Task done。
|
||
|
||
### RAGFlow create dataset 兼容性修复
|
||
|
||
已验证事实：
|
||
|
||
- 真实 RAGFlow `POST /api/v1/datasets` 带 `config:{}` 时返回 `code=101 Extra inputs are not permitted`。
|
||
- 真实 RAGFlow `POST /api/v1/datasets` 只发送 `name` 时返回 `code=0 data.id`。
|
||
- Muse adapter 已调整为 createDataset 只发送 `name`；`updateDatasetConfig` 仍保留独立提交 config 的能力。
|
||
- `pollDocumentStatuses` 已调整为使用真实支持的 `?id=<docId>`；多 document id 会在 Muse adapter 内 fail closed 为 `VALIDATION_ERROR`，避免生成 RAGFlow 不支持的批量查询。
|
||
|
||
## 推断
|
||
|
||
- New-API 服务、认证、模型路由、上游 LLM 调用、消费日志链路已经对 `MiniMax-M2.5` 跑通。
|
||
- P1R-4 之前阻塞的“New-API chat/completions 未验收成功”已解除。
|
||
- RAGFlow 服务、鉴权、dataset/document/chunk/retrieval 链路已经通过 Muse Knowledge runtime client 跑通。
|
||
- 仅凭 runtime client live acceptance 还不足以证明 Muse 自身 AI 41 个 operation 和 Knowledge 59 个 operation 已完成端到端验收；还需要 Muse API 触发、任务状态、runtime call、job 和审计链路证据。
|
||
|
||
## 剩余缺口
|
||
|
||
P1R-4 仍需补齐：
|
||
|
||
1. 通过 Muse dedicated AI API 触发一次真实 AI task，而不是只调用 runtime client。
|
||
2. 验证 Muse DB 中 task/job/runtime_call/event/audit 记录形成成功态。
|
||
3. 验证失败路径仍 fail closed，不因配置了真实 New-API 而伪造 success。
|
||
4. 经用户批准后，才可以申请把对应 AI operations 从 `needs_verification` 推进到 `completed`。
|
||
|
||
P1R-5 仍需补齐：
|
||
|
||
1. 通过 Muse dedicated Knowledge API 触发真实 dataset/document/retrieval 流程，而不是只调用 runtime client。
|
||
2. 验证 Muse DB 中 dataset/document/task/runtime_call/audit 记录形成成功态。
|
||
3. 验证失败路径仍 fail closed，不因配置了真实 RAGFlow 而伪造 success。
|
||
4. GraphRAG 需要确认默认 chat model、New-API 归因和 token 预算后再测。
|
||
5. 经用户批准后，才可以申请把对应 Knowledge operations 从 `needs_verification` 推进到 `completed`。
|
||
|
||
## 推荐下一步命令
|
||
|
||
加载 New-API 验收配置：
|
||
|
||
```bash
|
||
set -a
|
||
. muse-cloud/scripts/dev/p1r-external-acceptance.env
|
||
set +a
|
||
```
|
||
|
||
直接重跑 New-API chat smoke：
|
||
|
||
```bash
|
||
curl --noproxy '*' -sS -m 150 \
|
||
-H "Authorization: Bearer ${MUSE_AI_NEW_API_TOKEN}" \
|
||
-H 'Content-Type: application/json' \
|
||
--data '{"model":"MiniMax-M2.5","messages":[{"role":"user","content":"只输出 OK"}],"stream":false,"temperature":0}' \
|
||
"${MUSE_AI_NEW_API_BASE_URL}/v1/chat/completions"
|
||
```
|
||
|
||
Muse runtime adapter 方向应优先验证：
|
||
|
||
```bash
|
||
cd muse-cloud
|
||
set -a
|
||
. scripts/dev/p1r-external-acceptance.env
|
||
set +a
|
||
MUSE_P1R_EXTERNAL_ACCEPTANCE=true JAVA_HOME=$(/usr/libexec/java_home -v 21) \
|
||
mvn -pl muse-module-ai/muse-module-ai-server \
|
||
-Dtest=P1rNewApiLiveAcceptanceIT#shouldCallNewApiThroughMuseRuntimeClientAndPrintRedactedEvidence test
|
||
MUSE_P1R_EXTERNAL_ACCEPTANCE=true JAVA_HOME=$(/usr/libexec/java_home -v 21) \
|
||
mvn -pl muse-module-knowledge/muse-module-knowledge-server \
|
||
-Dtest=P1rRagFlowLiveAcceptanceIT#shouldCallRagFlowThroughMuseRuntimeClientAndPrintRedactedEvidence test
|
||
```
|
||
|
||
注意：上面的 Maven 测试是 runtime client live acceptance，不等价于 Muse API 端到端 completed 证据。真正 completed 证据必须包含 Muse API 层触发、Muse 运行时对 New-API/RAGFlow 的真实调用、Muse 侧落库链路、审计记录和失败路径。
|
||
|
||
## 新增 live acceptance harness
|
||
|
||
2026-06-02 新增两个默认跳过的 opt-in JUnit 验收入口，用于把当前 Muse runtime client 直接接到外部 New-API / RAGFlow，并输出脱敏 JSON 证据摘要：
|
||
|
||
- P1R-4：`muse-module-ai/muse-module-ai-server/src/test/java/cn/iocoder/muse/module/ai/application/muse/facade/P1rNewApiLiveAcceptanceIT.java`
|
||
- P1R-5：`muse-module-knowledge/muse-module-knowledge-server/src/test/java/cn/iocoder/muse/module/knowledge/application/muse/facade/P1rRagFlowLiveAcceptanceIT.java`
|
||
|
||
默认未设置 `MUSE_P1R_EXTERNAL_ACCEPTANCE=true` 时只跳过，不失败：
|
||
|
||
```bash
|
||
cd muse-cloud
|
||
JAVA_HOME=/Users/qingse/Library/Java/JavaVirtualMachines/corretto-21.0.7/Contents/Home \
|
||
mvn -pl muse-module-ai/muse-module-ai-server -Dtest=P1rNewApiLiveAcceptanceIT test
|
||
JAVA_HOME=/Users/qingse/Library/Java/JavaVirtualMachines/corretto-21.0.7/Contents/Home \
|
||
mvn -pl muse-module-knowledge/muse-module-knowledge-server -Dtest=P1rRagFlowLiveAcceptanceIT test
|
||
```
|
||
|
||
真实外部验收命令：
|
||
|
||
```bash
|
||
cd muse-cloud
|
||
set -a
|
||
. scripts/dev/p1r-external-acceptance.env
|
||
set +a
|
||
export MUSE_P1R_EXTERNAL_ACCEPTANCE=true
|
||
JAVA_HOME=/Users/qingse/Library/Java/JavaVirtualMachines/corretto-21.0.7/Contents/Home \
|
||
mvn -pl muse-module-ai/muse-module-ai-server -Dtest=P1rNewApiLiveAcceptanceIT test
|
||
JAVA_HOME=/Users/qingse/Library/Java/JavaVirtualMachines/corretto-21.0.7/Contents/Home \
|
||
mvn -pl muse-module-knowledge/muse-module-knowledge-server -Dtest=P1rRagFlowLiveAcceptanceIT test
|
||
```
|
||
|
||
说明：
|
||
|
||
- 当前 `muse-cloud` checkout 没有 `./mvnw`，本机验证使用 `mvn`；如果后续补回 Maven Wrapper，可把命令中的 `mvn` 替换为 `./mvnw`。
|
||
- harness 输出只打印 endpoint、模型、dataset/document id、状态、耗时、usage、token/key 长度和 sha256 前 12 位，不打印完整 token/key。
|
||
- P1R-5 RAGFlow smoke 会创建唯一 `p1r-live-时间戳` dataset 并保留，不做删除，便于外部验收取证。
|
||
- GraphRAG 默认不作为 completed 证据；`MUSE_KNOWLEDGE_RAGFLOW_GRAPHRAG_ATTRIBUTION_READY=false` 时只验证 Muse adapter fail closed 为 `ATTRIBUTION_NOT_CONFIGURED`。真实 GraphRAG run/trace 需要额外设置 `MUSE_KNOWLEDGE_RAGFLOW_GRAPHRAG_ATTRIBUTION_READY=true` 和 `MUSE_KNOWLEDGE_RAGFLOW_GRAPHRAG_DATASET_ID`。
|
||
- 该 harness 只提供外部依赖 live evidence，不等价于 coverage completed；coverage 仍需 Muse API 端到端调用、落库、任务状态、审计和失败路径证据后再单独申请更新。
|