Диагностика эмбеддингов

POST

/wp-json/wp2tutor/embedding/v1/diagnostics

const url = 'https://example.com/wp-json/wp2tutor/embedding/v1/diagnostics';
const options = {
  method: 'POST',
  headers: {'X-WP-Nonce': '<X-WP-Nonce>', 'Content-Type': 'application/json'},
  body: '{"query":"что такое эмбеддинг"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/wp-json/wp2tutor/embedding/v1/diagnostics \
  --header 'Content-Type: application/json' \
  --header 'X-WP-Nonce: <X-WP-Nonce>' \
  --data '{ "query": "что такое эмбеддинг" }'

Админский гибридный поиск по индексу (не продакшен-чат). PHP diagnostics: JSON { query }, sanitize_text_field, DiagnosticsRunner::run. Всегда HTTP 200: { logs, matches }. Отказ (пустой query, нет ключа, нет vec-таблицы, провайдер не вернул вектор) — не 4xx, а logs с текстом DiagnosticsAbortException и matches []. Совпадения: sqlite-vec kNN + FTS5, RRF, score 0–100 (HybridDiagnosticsScore, веса 0.7 vec / 0.3 FTS), обычно до 8 (FINAL_TOP_K). text — превью content до 200 символов без HTML. Нужно manage_options.

Authorizations

cookie
applicationPassword

Request Body

application/json

object

query

Текст запроса. PHP sanitize_text_field; нет ключа — ''. Пустая строка — 200, logs с Enter query text. (i18n), matches [].

string

Example

{
  "query": "что такое эмбеддинг"
}

Responses

200

Logs (шаги или одно abort-сообщение) и matches. Пустой query — logs вроде Enter query text., matches [].

application/json

object

logs

Шаги прогона. Успех: строки «Найдено совпадение {score}% в чанке №{id}: {text}». Abort: один элемент — сообщение DiagnosticsAbortException (нет query/ключа/vec-таблицы/эмбеддинга запроса).

Array<string>

matches

Найденные чанки (обычно ≤ 8). Abort — [].

Array<object>

object

id_chunk

ID фрагмента в индексе/SQLite.

integer

distance

Косинусное расстояние sqlite-vec (обычно 0…1). У FTS-only хитов PHP может подставить 1.0.

number

score

Гибридный процент 0–100 (HybridDiagnosticsScore: 0.7×(1−distance) + 0.3×норм. bm25), округление до 1 знака. Это не сырой cosine similarity.

number

fts_rank

Сырой bm25 FTS5, только если чанк попал в FTS-ногу. Иначе ключа нет.

number

text

Превью content без HTML, до 200 символов (пробелы схлопнуты). Нет строки чанка — ''.

string

Example

{
  "logs": [
    "Найдено совпадение 91.2% в чанке №42: Эмбеддинг — векторное представление текста."
  ],
  "matches": [
    {
      "id_chunk": 42,
      "distance": 0.12,
      "score": 91.2,
      "fts_rank": -4.2,
      "text": "Эмбеддинг — векторное представление текста."
    }
  ]
}

401

Не аутентифицирован. DualRest: rest_forbidden (status 401), если нет cookie-сессии. Cookie + X-WP-Nonce или Application Password.

application/json

object

code

Код WP_Error. Для POST /chat 401 — rest_forbidden. DualRest cookie — rest_forbidden / rest_not_logged_in / rest_cookie_invalid_nonce.

string

message

Сообщение WP_Error (для секрета чата — Missing or invalid secret.).

string

data

Обычно { status: HTTP-код }, как PHP кладёт в WP_Error data.

object

Example

{
  "code": "rest_forbidden",
  "message": "Missing or invalid secret.",
  "data": {
    "status": 401
  }
}

403

Нет права manage_options или невалидный REST nonce. WordPress REST: rest_forbidden / rest_cookie_invalid_nonce.

application/json

object

code

Код WP_Error. Для POST /chat 401 — rest_forbidden. DualRest cookie — rest_forbidden / rest_not_logged_in / rest_cookie_invalid_nonce.

string

message

Сообщение WP_Error (для секрета чата — Missing or invalid secret.).

string

data

Обычно { status: HTTP-код }, как PHP кладёт в WP_Error data.

object

Example

{
  "code": "rest_forbidden",
  "message": "Missing or invalid secret.",
  "data": {
    "status": 401
  }
}