Hayhooks

Hayhooks

Hayhooks는 Haystack 파이프라인을 HTTP 엔드포인트로 서빙할 수 있게 해 주는 웹 애플리케이션이에요. 이 페이지에서는 Hayhooks의 주요 기능을 개괄적으로 살펴볼게요.

출처: 공식문서

Hayhooks는 Haystack 파이프라인을 REST API로 배포하는 일을 훨씬 단순하게 만들어 줍니다. 이를 통해 다음과 같은 일을 할 수 있어요:

  • OpenAI 호환 채팅 엔드포인트를 포함해 Haystack 파이프라인을 HTTP 엔드포인트로 노출하고,
  • 최소한의 보일러플레이트만으로 로직을 커스터마이즈하며,
  • 파이프라인을 빠르고 효율적으로 배포할 수 있습니다.

상세 설정 레퍼런스, 고급 기능, 예제를 모두 보려면 공식 Hayhooks 문서를, 소스 코드는 Hayhooks GitHub 저장소를 참고하세요.

설치 (Installation)

pip로 Hayhooks를 설치합니다:

pip install hayhooks

hayhooks 패키지에는 서버와 클라이언트 컴포넌트가 함께 들어 있고, 클라이언트가 서버를 시작할 수 있어요. 셸에서 서버를 시작하려면:

$ hayhooks run
INFO:     Started server process [44782]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://localhost:1416 (Press CTRL+C to quit)

상태 확인 (Check Status)

다른 셸에서 서버 상태를 조회할 수 있어요:

$ hayhooks status
Hayhooks server is up and running.

설정 (Configuration)

Hayhooks는 세 가지 방식으로 설정할 수 있습니다:

  1. 프로젝트 루트의 .env 파일을 사용하거나,
  2. 명령 실행 시 환경 변수를 넘기거나,
  3. hayhooks run과 함께 명령줄 인자를 사용합니다.

서버 설정, CORS, SSL, 로깅, 스트리밍, Chainlit UI 옵션을 포함한 환경 변수의 전체 목록은 Hayhooks 환경 변수 레퍼런스에서 확인하세요.

Hayhooks 실행하기 (Running Hayhooks)

서버를 시작하려면:

hayhooks run

이러면 Hayhooks가 HAYHOOKS_HOST:HAYHOOKS_PORT에 뜹니다.

파이프라인 배포하기 (Deploying a Pipeline)

단계 (Steps)

  1. 파이프라인 정의(.yml 파일)와 pipeline_wrapper.py 파일을 준비하세요.

  2. 파이프라인을 배포합니다:

    hayhooks pipeline deploy-files -n my_pipeline my_pipeline_dir

  3. {pipeline_name}/run 엔드포인트에서 파이프라인에 접근합니다.

파이프라인 래퍼 (Pipeline Wrapper)

파이프라인을 감싸려면 PipelineWrapper 클래스가 필요해요:

from pathlib import Path
from haystack import Pipeline
from hayhooks import BasePipelineWrapper


class PipelineWrapper(BasePipelineWrapper):
    def setup(self) -> None:
        pipeline_yaml = (Path(__file__).parent / "pipeline.yml").read_text()
        self.pipeline = Pipeline.loads(pipeline_yaml)

    def run_api(self, input_text: str) -> str:
        result = self.pipeline.run({"input": {"text": input_text}})
        return result["output"]["text"]

파일 업로드 (File Uploads)

파이프라인 래퍼의 run_api 메서드에 files: list[UploadFile] | None = None 인자를 포함하면 Hayhooks가 파일 업로드를 처리해 줍니다.

def run_api(self, files: list[UploadFile] | None = None) -> str:
    if files and len(files) > 0:
        filenames = [f.filename for f in files if f.filename is not None]
        file_contents = [f.file.read() for f in files]
        return f"Received files: {', '.join(filenames)}"
    return "No files received"

업로드된 파일이 있으면 Hayhooks가 자동으로 처리해 run_api 메서드에 전달해요. 이때 HTTP 요청은 multipart/form-data 요청이어야 합니다. 파일을 파라미터와 함께 조합하는 방법을 포함한 더 자세한 내용은 공식 Hayhooks 문서를 참고하세요.

CLI에서 파이프라인 실행하기 (Running Pipelines from the CLI)

hayhooks pipeline run 명령으로 파이프라인을 명령줄에서 실행할 수 있어요. 내부적으로는 파이프라인 래퍼의 run_api 메서드를 호출하며, 파라미터는 JSON 페이로드로 전달됩니다.

hayhooks pipeline run <pipeline_name> --param 'question="Is this recipe vegan?"'

파이프라인을 실행할 때 파일을 업로드할 수도 있어요:

hayhooks pipeline run <pipeline_name> --file file.pdf --param 'question="Is this recipe vegan?"'

전체 CLI 레퍼런스는 Hayhooks CLI 문서에서 확인하세요.

MCP 지원 (MCP Support)

Hayhooks는 Model Context Protocol (MCP)을 지원하며 MCP 서버 역할을 할 수 있어요. 배포된 파이프라인과 에이전트를 Streamable HTTP(권장)와 Server-Sent Events(SSE, 하위 호환용으로 유지) 양쪽에서 MCP Tool로 자동으로 나열합니다. 에이전트는 파이프라인과 동일한 PipelineWrapper 메커니즘으로 배포됩니다.

MCP 지원은 선택적(optional) 추가 기능이에요. 설치하고 Hayhooks MCP 서버를 시작하려면:

pip install "hayhooks[mcp]"
hayhooks mcp run

배포된 각 파이프라인에 대해 Hayhooks는 파이프라인 래퍼 이름을 MCP Tool 이름으로 사용하고, run_api 메서드 인자에서 도구 스키마를 생성해요. MCP 도구 설정에 대한 자세한 내용은 Hayhooks MCP 문서를 참고하세요.

OpenAI 호환성 (OpenAI Compatibility)

Hayhooks는 run_chat_completion 메서드를 통해 OpenAI 호환 엔드포인트를 지원합니다.

from hayhooks import BasePipelineWrapper, get_last_user_message


class PipelineWrapper(BasePipelineWrapper):
    def run_chat_completion(self, model: str, messages: list, body: dict):
        question = get_last_user_message(messages)
        return self.pipeline.run({"query": question})

이 덕분에 Hayhooks 파이프라인은 스트리밍 응답을 포함해 OpenAI 채팅 완성 API를 지원하는 어떤 도구와도 호환됩니다. 자세한 내용은 Hayhooks OpenAI 호환성 문서를 확인하세요.

프로그래밍 방식으로 실행하기 (Running Programmatically)

Hayhooks는 FastAPI 애플리케이션에 내장(embed)할 수도 있어요:

import uvicorn
from hayhooks.settings import settings
from fastapi import Request
from hayhooks import create_app

# Create the Hayhooks app
hayhooks = create_app()


# Add a custom route
@hayhooks.get("/custom")
async def custom_route():
    return {"message": "Hi, this is a custom route!"}


# Add a custom middleware
@hayhooks.middleware("http")
async def custom_middleware(request: Request, call_next):
    response = await call_next(request)
    response.headers["X-Custom-Header"] = "custom-header-value"
    return response


if __name__ == "__main__":
    uvicorn.run("app:hayhooks", host=settings.host, port=settings.port)

이렇게 하면 기본 Hayhooks 앱에 커스텀 라우트나 미들웨어를 얹어 자기 애플리케이션에 그대로 녹여 쓸 수 있어요.

더 알아보기 (Learn more)