На этой странице
Как Core выполняет поиск¶
Начните с границы HTTP¶
POST /api/v1/spaces/{space_id}/search принимает запрос и возвращает
ранжированные фрагменты. Маршрут
Caddy
Направляет
/api/*в Django.DocumentSearch.post
Передаёт инициатора, UUID пространства и типизированное тело запроса.
RetrieveDocuments
Проверяет доступ, фильтры и готовность корпуса.
QueryEngine
Ищет и ранжирует фрагменты.
@modify(
status_code=HTTPStatus.OK,
operation_id='searchSpace',
extra_responses=raises(
exceptions.CorpusNotInitializedError,
exceptions.CorpusRecoveringError,
exceptions.CorpusChangedError,
exceptions.SpaceNotFoundError,
exceptions.InvalidMetadataFilterError,
exceptions.QueryFilterUnsupportedError,
exceptions.RetrievalSettingsUnsupportedError,
exceptions.LLMNotConfiguredError,
exceptions.SpaceStorageUnreachableError,
exceptions.StoredPointUnreadableError,
exceptions.LateChunkingPoolingError,
),
)
@inject
@mcp_tool(
name='search_knowledge_base',
description=(
'Search a knowledge base and get back the passages that match, '
'ranked, with no answer written for you. Prefer this over '
'answer_from_knowledge_base: you can read the passages and '
'reason over them yourself, which is cheaper and keeps your own '
'context. Passage texts come back shortened; call fetch_source '
'with a passage id to read one in full.'
),
input_fields=('query', 'top_k'),
max_top_k=RETRIEVAL_TOP_K_CEILING,
cost=ToolCost.cheap,
)
async def post(
self,
parsed_path: Path[DocumentPath],
parsed_body: BodyMsgspec[RetrievalRequestPayload],
retrieve_documents: FromDishka[RetrieveDocuments],
) -> RetrieveResultPayload:
"""Retrieve and rank the most relevant chunks, without generating.
Only a member of the space may search it: a non-member is told the space
was not found. Searching only needs read access, which every membership
role grants, so a member is never forbidden -- no 403 arises here.
Plain retrieval needs no LLM, but a read path that names an LLM step
(HyDE, the LLM-judge reranker) does; a space that named one with no LLM
configured is answered with a 409.
A request that narrows the search settles its filter first: a filter
breaking the bounds, or naming something the space was never declared
to be selectable by, is a 400, and one its retrieval legs could not
honour is a 409 rather than a search quietly made around it.
"""
principal = principal_from_request(self.request)
return await retrieve_documents(
principal,
parsed_path.space_id,
parsed_body,
)
Проследите сценарий и его контракты¶
Контроллер разбирает тело как
RetrievalRequestPayload.
Фабрика Dishka
предоставляет зависимости запроса в области SESSION.
RetrieveDocuments
проверяет право SpaceAction.view, поддержку фильтра метаданных и
готовность корпуса. Затем вызывает
QueryEngine.retrieve_sources
по исходящему маршруту пространства. Настроенный этап может вызвать модель,
например для переформулировки запроса.
Поиск возвращает источники и сведения о ранжировании в RetrieveResultPayload. За генерацию ответа отвечает QueryDocuments.
Контроллеры. Разбирайте HTTP-запрос и описывайте ответ. Используйте публичные UUID в маршрутах и DTO.
logic. Здесь находятся проверки доступа и решения сценария. Для заменяемой инфраструктуры заведите порт и подключите реализацию в DI.infraиmodels. Читайте через селекторы, записывайте через мутации и преобразуйте данные мапперами. Запросы ORM находятся вinfra, схемы — вmodels. При изменении выборки или записи добавьте целевой тест.Области DI. Общие службы используют область приложения, зависимости запроса — область запроса или сессии. Middleware открывает дочернюю область для каждого запроса. Сборка контейнера
Для сравнения проследите запись¶
Контроллер загрузки проверяет multipart-запрос и вызывает IngestDocument. Сценарий проверяет доступ, метаданные и права записи, затем загружает ревизию в управляемый корпус или добавляет данные в подключённое хранилище. Реализация порта извлечения заменяется независимо от HTTP. У загрузки, замены оригинала и переиндексации свои контракты. Обработка и индексация
Проверяйте реальный маршрут со сборкой DI и правилами доступа. Опубликованные данные прочитайте с подходящими правами. На том же маршруте проверьте отказ из-за отсутствия доступа, неверного фильтра или недоступного провайдера.