На этой странице

Как Core выполняет поиск

Начните с границы HTTP

POST /api/v1/spaces/{space_id}/search принимает запрос и возвращает ранжированные фрагменты. Маршрут

  1. Caddy

    Направляет /api/* в Django.

  2. DocumentSearch.post

    Передаёт инициатора, UUID пространства и типизированное тело запроса.

  3. RetrieveDocuments

    Проверяет доступ, фильтры и готовность корпуса.

  4. 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 и правилами доступа. Опубликованные данные прочитайте с подходящими правами. На том же маршруте проверьте отказ из-за отсутствия доступа, неверного фильтра или недоступного провайдера.

ContextBase0.1.0

Поиск в документации