startup_script.py 은 어떻게 작성해?
- User
startup_script.py 은 어떻게 작성해?
- Assistant
아래 예시는
PYTHONSTARTUP환경 변수를 써서 vLLM 서빙을 시작하기 전에 여러분의 플러그인 코드를 로드·등록하는 아주 단순한 패턴입니다.-
먼저, 여러분의 플러그인 패키지(예:
your_plugin_package) 안에register_plugin()같은 함수가 있다고 가정합니다.# your_plugin_package/__init__.py def register_plugin(): """ vLLM의 entry_points 에 해당하는 모델을 런타임에 동적으로 등록한다. (실제 구현은 vLLM 확장 가이드에 맞춰 작성) """ from vllm.model_executor.models import register_model_executor_loader from .model import YourCustomModelClass # 예시) 'your_model_name' 이라는 이름으로 클래스 등록 register_model_executor_loader("your_model_name", YourCustomModelClass) -
그 다음,
startup_script.py를 이렇게 작성하세요.
# startup_script.py import sys import os # 1) 플러그인 패키지의 위치를 PYTHONPATH 에 추가 PLUGIN_PATH = "/absolute/path/to/your_plugin_package" if PLUGIN_PATH not in sys.path: sys.path.insert(0, PLUGIN_PATH) # (선택) 로그 남기기 print(f"[startup_script] added plugin path: {PLUGIN_PATH}") # 2) 플러그인 패키지의 등록 함수 호출 try: from your_plugin_package import register_plugin print("[startup_script] found register_plugin(), calling it…") register_plugin() print("[startup_script] plugin registered successfully.") except Exception as e: print(f"[startup_script] ⚠️ failed to register plugin: {e}") # 3) (선택) 추가로 환경 변수나 설정을 조정할 수 있음 # os.environ["VLLM_SOME_OPTION"] = "value"- 이제 서버 시작 시 이렇게 실행해 주세요:
export PYTHONSTARTUP=/absolute/path/to/startup_script.py vllm serve --model your_model_name --trust-remote-code–
PYTHONSTARTUP스크립트는 Python 인터프리터 시작 시(대화형 REPL뿐 아니라 스크립트 실행 시에도) 항상 로드되므로, 위와 같이 설정하면vllm serve를 실행할 때도 자동으로 실행됩니다.
–register_plugin()안에서는 여러분이entry_points로 했던 것과 동일하게 런타임에 vLLM 모델 로더에 등록해 주면 됩니다.이렇게 하면 별도의
setup.py재설치 없이도 플러그인을 동적으로 붙여서 vLLM을 서빙할 수 있습니다.❗️주의:--trust-remote-code옵션을 꼭 함께 사용하세요. -
- User
python에서 setup.py 가 어떤 역할이야?
- Assistant
Python 프로젝트에서
setup.py는 주로 setuptools를 이용한 패키지의 “빌드·설치·배포”를 정의하는 스크립트입니다. 한마디로, 여러분의 코드를 외부에 배포하거나, 로컬·원격 저장소(예: PyPI)에 올리거나,pip install .로 설치할 때 동작하는 설정 파일이죠.아래에서
setup.py의 역할과 주요 구성 요소를 정리해 보겠습니다.
1.
setup.py의 주요 역할- 패키지 메타데이터 정의
- 이름(name), 버전(version), 설명(description), 저자(author) 등
- 의존성(dependencies) 관리
install_requires로 패키지가 설치될 때 필요한 라이브러리 나열
- 패키지·모듈 목록 지정
packages또는py_modules로 배포할 파이썬 모듈/패키지 지정
- Entry Point(엔트리 포인트) 설정
- 커맨드라인 스크립트(
console_scripts)나 vLLM 같은 플러그인 시스템 등록
- 커맨드라인 스크립트(
- 패키징 옵션
- 포함할 패키지 데이터(비코드 파일), 라이선스, 분류(Classifier) 등
2.
setup.py예시from setuptools import setup, find_packages setup( name="my_awesome_pkg", version="0.1.0", description="An awesome package for demonstration", author="Your Name", author_email="you@example.com", url="https://github.com/you/my_awesome_pkg", license="MIT", packages=find_packages(), # 프로젝트 내 모든 서브패키지 자동 포함 python_requires=">=3.7", # 최소 파이썬 버전 install_requires=[ # 의존성 패키지 "numpy>=1.20", "requests", ], entry_points={ # 커맨드라인 스크립트 예시 "console_scripts": [ "run-awesome = my_awesome_pkg.cli:main", ], # vLLM 플러그인 예시 "vllm.model_executor_loader": [ "my_model = my_awesome_pkg.vllm_ext:MyCustomModel", ], }, include_package_data=True, # MANIFEST.in으로 지정한 데이터 포함 classifiers=[ # PyPI 분류 "Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", ], )
3. 동작 흐름
python setup.py sdist bdist_wheel
→ 소스 배포판(sdist)과 바이트 휠(wheel) 파일 생성pip install .또는pip install my_awesome_pkg
→install_requires에 명시된 패키지까지 한꺼번에 설치- Entry Point에 등록된 스크립트나 플러그인이 시스템에 자동 등록
4. 최근 트렌드:
pyproject.tomlPEP 517/518 기반의 현대적인 빌드 시스템은
pyproject.toml에 설정을 두기도 합니다.build-system에 빌드 백엔드(setuptools, poetry 등) 지정- 패키징 메타데이터와 의존성을 TOML 형식으로 선언
그러나 기존 환경과 높은 호환성을 원한다면 여전히
setup.py를 많이 사용합니다.
5. 정리
setup.py는 패키지 설치·배포·메타데이터의 허브- 의존성 관리, entry point 등록, 패키징 옵션 등을 한곳에 정의
pip install,python setup.py install같은 명령의 밑단에서 동작
패키지를 외부에 배포하거나, 프로젝트 내에서 모듈을 재활용할 계획이 있다면
setup.py를 꼭 익혀 두시는 걸 추천드립니다.🚀 - 패키지 메타데이터 정의
- User
entry_points 가 뭐야
- Assistant
entry_points는 setuptools(또는 pip) 패키지에 “플러그인”이나 “커맨드라인 스크립트”를 선언해서,
패키지 설치 시 자동으로 등록·노출되게 해 주는 메커니즘입니다.
1. entry_points의 주요 용도
- console_scripts
- 설치 시 스크립트를 생성해서
$ your-cmd형태로 커맨드라인에서 바로 실행 가능
- 설치 시 스크립트를 생성해서
- gui_scripts
- GUI 앱 런처 스크립트 등록
- 기타 커스텀 그룹
- vLLM 같은 외부 라이브러리에서 플러그인으로 “어디에 어떤 클래스를 로드할지” 지정
2. 선언 형식
# setup.py from setuptools import setup, find_packages setup( name="my_pkg", version="0.1.0", packages=find_packages(), entry_points={ # 1) 커맨드라인 스크립트 예시 "console_scripts": [ "my-cmd = my_pkg.cli:main", # 설치 후 'my-cmd' 치면 my_pkg/cli.py 의 main() 실행 ], # 2) vLLM 플러그인 예시 "vllm.model_executor_loader": [ "custom_model = my_pkg.vllm_ext:CustomModelClass", ], }, )"그룹명": setuptools가 해석하는 키."이름 = 모듈경로:객체"- 이름: 실제 사용할 커맨드 (
console_scripts)나 모델 식별자 (vllm에서--model custom_model) - 모듈경로:객체: 해당 이름을 호출했을 때 로드될 함수/클래스 경로
- 이름: 실제 사용할 커맨드 (
3. 동작 방식
pip install .등을 통해 패키지를 설치하면- 설치된 패키지의
entry_points정보가 메타데이터에 기록 -
console_scripts는 운영체제에 실행 래퍼(wrapper)를 만들어 줌vllm.model_executor_loader같은 커스텀 그룹은 vLLM이 런타임에 찾아서 동적 로드
4. vLLM에서의 활용 예시
- setup.py에 등록:
entry_points={ "vllm.model_executor_loader": [ "my_model = my_pkg.vllm_ext:MyCustomModelClass" ], } - 설치 후:
→ vLLM이vllm serve --model my_model --trust-remote-codemy_modelentry point를 찾아MyCustomModelClass를 로드해 서빙
5. 요약
- entry_points는 설치 시점에 패키지를 외부(터미널 명령어, 다른 라이브러리 플러그인 등)에 연결해 주는 설정
"그룹명"별로 다양한 용도로 쓰이며, 특히 콘솔 스크립트나 플러그인 시스템 구현에 필수적
이제 setup.py에 entry_points를 추가하면 자동으로 여러분의 커스텀 기능을 등록·노출시킬 수 있습니다! 🚀
- console_scripts
- User
INFO 07-04 02:55:51 init.py:62] Available plugins: INFO 07-04 02:55:51 init.py:64] name=custom_lora_resolver, value=register_custom_lora_resolver:register, group=vllm.general_plugins INFO 07-04 02:55:51 init.py:71] plugins to load: ['custom_lora_resolver'] ERROR 07-04 02:55:51 init.py:79] Failed to load plugin custom_lora_resolver ERROR 07-04 02:55:51 init.py:79] Traceback (most recent call last): ERROR 07-04 02:55:51 init.py:79] File "/usr/local/lib/python3.12/dist-packages/vllm/plugins/init.py", line 75, in load_general_plugins ERROR 07-04 02:55:51 init.py:79] func = plugin.load() ERROR 07-04 02:55:51 init.py:79] ^^^^^^^^^^^^^ ERROR 07-04 02:55:51 init.py:79] File "/usr/lib/python3.12/importlib/metadata/init.py", line 205, in load ERROR 07-04 02:55:51 init.py:79] module = import_module(match.group('module')) ERROR 07-04 02:55:51 init.py:79] ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ERROR 07-04 02:55:51 init.py:79] File "/usr/lib/python3.12/importlib/init.py", line 90, in import_module ERROR 07-04 02:55:51 init.py:79] return _bootstrap._gcd_import(name[level:], package, level) ERROR 07-04 02:55:51 init.py:79] ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ERROR 07-04 02:55:51 init.py:79] File "", line 1387, in _gcd_import ERROR 07-04 02:55:51 init.py:79] File "", line 1360, in _find_and_load ERROR 07-04 02:55:51 init.py:79] File "", line 1324, in _find_and_load_unlocked ERROR 07-04 02:55:51 init.py:79] ModuleNotFoundError: No module named 'register_custom_lora_resolver' INFO 07-04 02:55:52 config.py:478] This model supports multiple tasks: {'reward', 'classify', 'score', 'generate', 'embed'}. Defaulting to 'generate'.
- Assistant
아래 에러 메시지를 보면, 여러분이
entry_points에 이렇게 등록하셨을 거예요:[vllm.general_plugins] custom_lora_resolver = register_custom_lora_resolver:register하지만 실제로 파이썬이
import register_custom_lora_resolver를 시도하다가 모듈을 찾지 못해서ModuleNotFoundError를 뱉고 있죠.
즉,entry_points에 지정한 “모듈 경로” 가 잘못된 겁니다.
1. “모듈 경로:함수” 의 올바른 형태
entry_points 에는 반드시
“[실제로 설치된 패키지 내부] . [파일명]” 형태의 정확한 모듈 경로를 써 주셔야 합니다.
예를 들어, 프로젝트 구조가 다음과 같다고 가정합시다:my_lora_plugin/ ├── setup.py └── my_lora_plugin/ ├── __init__.py └── resolver.py # 여기에서 register() 함수를 정의resolver.py 안에:
# my_lora_plugin/resolver.py def register(): from vllm.plugins import register_general_plugin # 예시) 'custom_lora_resolver' 라는 이름으로 등록 register_general_plugin("custom_lora_resolver", _your_callback_func)이제 setup.py 에서는 entry_points 를 이렇게 적어야 합니다:
# setup.py from setuptools import setup, find_packages setup( name="my-lora-plugin", version="0.1.0", packages=find_packages(), entry_points={ "vllm.general_plugins": [ # <식별자> = <패키지명>.<모듈명>:<callable 이름> "custom_lora_resolver = my_lora_plugin.resolver:register", ], }, )my_lora_plugin.resolver가 import 가능한 경로여야 하고- 그 뒤에
:register라는 함수가 실제로 정의되어 있어야 에러 없이 로드됩니다.
2. 설치 & 확인
- 로컬로 개발 모드 설치
cd /path/to/my_lora_plugin pip install -e . - vLLM 서빙 실행
vllm serve --model your_model \ --trust-remote-code - 로그를 보면
처럼 “value” 에 여러분이 지정한 경로가 보이면 정상입니다.INFO … Available plugins: INFO … name=custom_lora_resolver, value=my_lora_plugin.resolver:register, group=vllm.general_plugins INFO … plugins to load: ['custom_lora_resolver']
3. 디버깅 팁
- pip 에서 실제로 설치된 entry point 를 확인하려면:
python -c "import importlib.metadata as m; print(m.entry_points().get('vllm.general_plugins'))" - 모듈이 설치된 위치를 확인하려면:
python -c "import my_lora_plugin; print(my_lora_plugin.__file__)" - 경로(
my_lora_plugin.resolver) 가 틀리면 당연히 import 에러가 납니다. 디렉토리·패키지 이름을 다시 한 번 점검하세요.
4. 정리
- entry_points 에 등록할 때는 항상 정확한 파이썬 import 경로(
package.submodule:callable) 를 사용 pip install -e .로 설치 후 실제로 등록된 엔트리 포인트를 확인vllm.general_plugins→ 여러분의 register 함수가register_general_plugin(...)을 부르게 하면 플러그인이 로드됨
이렇게만 맞춰주시면
Failed to load plugin custom_lora_resolver같은 에러 없이 정상적으로 플러그인이 로드될 거예요! 🚀
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.