在使用 Cadence JedAI（Joint Enterprise Data and AI Platform）时，偶尔会遇到如下报错：

1

422 Client Error: Unprocessable Entity for url: http://jedai:6000/embed

本文总结该问题的根因与解决方案，参考了 Cadence ASK 官方文档 JedAI Platform (Server) User Guide — JedAI Embedding Models（版本 25.14，2026 年 3 月）。

1. 错误解读

1.1 422 是什么意思？

HTTP 422 Unprocessable Entity 表示服务器收到了请求，但无法处理请求体，通常是因为请求 JSON 的字段名、字段类型或格式与服务端期望不符。

与 400（Bad Request，请求格式本身有问题）不同，422 说明服务端能解析 JSON，但其中的数据语义不合法。

1.2 /embed 路径从哪里来？

JedAI 对 lite_config.yml 中 embedding_url 的处理有明确规则：

配置的 embedding_url 实际调用路径
http://host:port/v1 http://host:port/v1/embeddings（通用模型）
http://host:port/v1/embedding（JEDAI_MODEL_INT_EMBED_* 代理模式，单数形式）
http://host:port/embed（不以 /v1 结尾） http://host:port/embed（原样使用，不追加任何路径）

出现 /embed 路径，说明 lite_config.yml 里写的是：

1
2

index_server:
  embedding_url: http://jedai:6000/embed

服务端收到 JedAI 请求后返回 422，说明请求体格式不匹配。

2. 根因分析

2.1 请求格式冲突

JedAI（HTTP provider）发送的是 OpenAI 兼容格式：

1
2
3
4
5

POST /embed
{
  "model": "JEDAI_MODEL_INT_EMBED_2",
  "input": ["How are you?", "That is awesome!"]
}

如果端口 6000 运行的是 HuggingFace text-embeddings-inference（TEI） 服务，TEI 期望的格式是：

1
2
3
4

POST /embed
{
  "inputs": ["How are you?", "That is awesome!"]
}

input（单数，OpenAI 格式）vs inputs（复数，TEI 格式）— 字段名不一致，TEI 服务端无法识别，直接返回 422。

2.2 模型未加载

即使端点路径正确，若 jedai:6000 上没有加载对应的 embedding 模型，服务端同样会返回 422。Cadence 官方文档的提示：

If legacy defaults are missing, the system may fall back to JEDAI_MODEL_INT_EMBED_2 and fail in environments where that model does not exist.

3. 解决方案

3.1 改用 /v1 标准路径（推荐）

将 lite_config.yml 中的 embedding_url 末尾改为 /v1，让 JedAI 自动拼接正确的子路径：

1
2
3
4

index_server:
  embedding_provider: http
  embedding_model: JEDAI_MODEL_INT_EMBED_2
  embedding_url: http://jedai:6000/v1   # 必须以 /v1 结尾

JedAI 会自动调用 http://jedai:6000/v1/embedding（JEDAI_MODEL_INT_EMBED_* 代理模式）或 http://jedai:6000/v1/embeddings（通用模型）。

3.2 升级到 25.14-s001+ 并使用多模型配置

25.14-s001 开始支持多 embedding 模型，推荐写法：

1
2
3
4
5
6
7
8
9
10
11

index_server:
  # 保留旧字段保证向后兼容
  embedding_provider: http
  embedding_model: JEDAI_MODEL_INT_EMBED_2
  embedding_url: http://jedai:6000/v1
  # 新增多模型列表
  embedding_models:
    - name: JEDAI_MODEL_INT_EMBED_2
      provider: http
      model: JEDAI_MODEL_INT_EMBED_2
      embedding_url: http://jedai:6000/v1

重要：即使启用了 embedding_models 列表，也要保留旧的单模型字段（embedding_model、embedding_url），否则部分请求路径（如 query / retrieve_doc）在未显式指定模型名时会回退到默认模型解析，若旧字段缺失则会报错。

3.3 验证 embedding 服务状态

修改配置、重启服务后，用以下命令验证：

1
2
3
4
5
6
7

# 查看服务已加载的 embedding 模型列表
curl http://jedai:6000/v1/index/embedding_models

# 手动测试 embedding 接口
curl -X POST 'http://jedai:6000/v1/embeddings' \
  -H 'Content-Type: application/json' \
  -d '{"model": "JEDAI_MODEL_INT_EMBED_2", "input": ["How are you?"]}'

也可以用 Python 验证：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

import requests
import getpass

jedai_url = "http://jedai:6000"
password = getpass.getpass("password:")

token = requests.post(
    f"{jedai_url}/api/v1/security/login",
    headers={"Content-Type": "application/json"},
    json={"username": getpass.getuser(), "password": password, "provider": "LDAP"}
).json()["access_token"]

response = requests.post(
    f"{jedai_url}/api/copilot/v1/llm/embeddings",
    headers={"accept": "*/*", "Content-Type": "application/json",
             "Authorization": f"Bearer {token}"},
    json={"model": "JEDAI_MODEL_INT_EMBED_2", "input": "How are you?"}
)
print(response.json())

4. 排查流程图

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

422 on http://jedai:6000/embed
        │
        ├─ embedding_url 末尾是 /embed？
        │     └─ 是 ──► 改为 http://jedai:6000/v1
        │
        ├─ jedai:6000 是 TEI 服务？
        │     └─ 是 ──► TEI 不兼容 OpenAI 格式
        │                ──► 在 6000 前加一个 OpenAI 兼容代理层
        │                    或换用 OpenAI 格式的 embedding 服务
        │
        ├─ curl GET /v1/index/embedding_models 返回空列表？
        │     └─ 是 ──► 模型未加载，检查模型路径配置
        │
        └─ 仍复现 ──► 开 Cadence Support Case
                      提供 lite_config.yml 和完整错误日志

5. 版本说明

版本 embedding 配置方式
25.14-s001 之前 仅支持单模型，使用 embedding_provider / embedding_model / embedding_url
25.14-s001 及以后 支持多模型列表 embedding_models，同时保留旧字段兼容

参考资料