{"id":18964095,"url":"https://github.com/janeliascicomp/sam_service","last_synced_at":"2026-03-04T04:01:14.361Z","repository":{"id":158355684,"uuid":"633462621","full_name":"JaneliaSciComp/SAM_service","owner":"JaneliaSciComp","description":"Web service which generates Segment Anything models","archived":false,"fork":false,"pushed_at":"2024-06-10T17:30:24.000Z","size":2512,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-11-17T04:13:37.314Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JaneliaSciComp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-27T14:49:48.000Z","updated_at":"2024-06-19T13:35:52.000Z","dependencies_parsed_at":"2023-11-16T23:58:55.600Z","dependency_job_id":"bc13dca1-e96a-4b2f-ac63-f4caecdad0db","html_url":"https://github.com/JaneliaSciComp/SAM_service","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/JaneliaSciComp/SAM_service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JaneliaSciComp%2FSAM_service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JaneliaSciComp%2FSAM_service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JaneliaSciComp%2FSAM_service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JaneliaSciComp%2FSAM_service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JaneliaSciComp","download_url":"https://codeload.github.com/JaneliaSciComp/SAM_service/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JaneliaSciComp%2FSAM_service/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30071670,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T03:25:38.285Z","status":"ssl_error","status_checked_at":"2026-03-04T03:25:05.086Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T14:22:43.152Z","updated_at":"2026-03-04T04:01:14.335Z","avatar_url":"https://github.com/JaneliaSciComp.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\n# SAM Service\n\nSAM Service is a Python-based web service that utilizes FastAPI and Uvicorn to create a fast and efficient API for retrieving a Segment Anything model. It also uses Nginx as a reverse proxy for handling HTTPS and improving performance. SAM stands for \"Segment Anything Model,\" and the service is designed to make it easy for developers to generate an embedded image model for use with an ONNX runtime.\n\nThis service supports canceling pending requests, so that the client (e.g. [Paintera](https://github.com/saalfeldlab/paintera)) can send speculative requests and then cancel them before they are processed on the GPU. This is implemented using a work queue and shared state among the worker threads, as illustrated below. \n\n![sam_service](https://github.com/JaneliaSciComp/SAM_service/assets/607324/859362e4-0337-430f-a116-060ffcf164e1)\n\n\n## Getting Started\n\nFollow the steps below to run the SAM Service. Please note that these steps were performed on Ubuntu linux. Your packages and package manager commands (e.g. `apt`) may vary.\n\n1. Make sure you have the cuda libraries installed.\n```\nsudo apt install nvidia-cuda-toolkit\n```\n\n1. Clone the repository: \n```\ngit clone git@github.com:JaneliaSciComp/SAM_service.git\n```\n2. Copy the model checkpoint file to the sam_service directory\n\n - These can be downloaded from https://github.com/facebookresearch/segment-anything#model-checkpoints\n - The `sam_vit_h_4b8939.pth` checkpoint is known to work\n  \n```\ncp sam_vit_h_4b8939.pth SAM_service/sam_service\n```\n\n3. Install the necessary packages using conda: \n```\nconda env create -f environment.yml\nconda activate segment_anything\n```\n\n4. Clone the paintera-sam repo alongside this one\n```\ncd ..\ngit clone git@github.com:cmhulbert/paintera-sam.git\ncd paintera-sam\npip install --user -e .\n```\n\n5. Start the API: \n```\ncd sam_service\nuvicorn sam_queue:app --access-log --workers 1 --host 0.0.0.0\n```\n\nNote that using one worker is very important here. Using more than one worker will spin up additional processes and each one will try to use the configured GPUs. The FAST API layer is async and doesn't require more than one worker to handle many clients.\n\n## Deploying in Production \n\n## Bare Metal\n\nYou can also set up everything yourself on bare metal. In production we use Nginx as a reverse proxy to handle and terminate HTTPS traffic. In this mode, Uvicorn is configured to run on a socket for improved performance. \n\n1. Clone this repository into /opt/deploy/SAM_service\n\n2. Follow the other setps in \"Getting Started\" above\n\n3. Link the Systemd file and start the Uvicorn service:\n\n```\nsudo ln -s /opt/deploy/SAM_service/systemd/sam.service /etc/systemd/system/sam.service\nsudo systemctl daemon-reload\nsudo systemctl enable sam.service\nsudo systemctl start sam.service\n```\n\n4. View the logs to make sure the service came up correctly:\n\n```\nsudo journalctl -fu sam.service\n```\n\n5. Install and configure nginx with the file found in `nginx.conf`\n\n```\nsudo apt-get install nginx\nsudo cp ./systemd/nginx.conf /etc/nginx/sites-enabled/sam_service\nsudo rm /etc/nginx/sites-enabled/default\nsudo systemctl enable nginx\nsudo systemctl start nginx\n```\n\n3. Connect to the service in your browser at `https://your-server-name`\n\n### Docker Compose\n\nNote: this has been prototyped but is not yet used in any deployment.\n\nTo run this service using Docker, you must first [configure Docker to work with GPUs](https://saturncloud.io/blog/how-to-use-gpu-from-a-docker-container-a-guide-for-data-scientists-and-software-engineers/). Also, you must use a recent version of docker-compose which has GPU support. The 2.24.5 version is known to work. The following command can be used to test whether Docker is set up correctly:\n\n```\ndocker run -it --rm --gpus all ubuntu nvidia-smi\n```\n\nThe `docker-compose.yml` assumes that you put the TLS certificates in /opt/deploy/ssl. The certificate files should be named `fullchain.pem` and `privkey.pem`. \n\nYou should also edit `nginx.conf` to set the server_name to the domain name of your server.\n\nFinally, to start the services run the following:\n```\ncd docker\ndocker-compose up\n```\n\nTo rebuild and push the Docker container, execute the following commands where `\u003cversion\u003e` is the version number you want to publish:\n\n```\ndocker build . -t ghcr.io/janeliascicomp/sam_service:\u003cversion\u003e\ndocker push ghcr.io/janeliascicomp/sam_service:\u003cversion\u003e\n```\n\n## Common Issues\n\n### Nginx can't connect to port 80\n\nYou may have another service (like Apache) already listening on that port. Shut down that service before starting up nginx, e.g. `sudo systemctl stop apache2`\n\n## Testing\n\nThere are scripts in the `./test` directory which can be used to verify that the service is working as intended, and to run stress tests. Use the `segment_anything` conda environment created above.\n\nThe following command starts 3 worker processes and each one submits 10 requests to the service, one at a time:\n```\npython tests/test_load.py -u http://localhost:8080 -i tests/em1.png -w 3 -r 10\n```\n\nThis command starts 10 worker processes and each one submits 2 requests in parallel using a thread pool:\n```\npython tests/test_cancel.py -u http://f15u30:8000 -i tests/em1.png -w 10 -r 2 --describe\n```\n\n## Endpoint Documentation\n\nDocumentation for the endpoints is provided by the service and can be found at the `/docs` or `/redoc` URLs.\n\n## Configuration\n\nSAM Service can be configured by modifying the `config.json` file. The following keys\n\n* `LOG_LEVEL`: maximum level of logging (`TRACE`, `DEBUG`, `INFO`, `WARNING`, `ERROR`)\n* `MODEL_TYPE`: Segment Anything [model type](https://github.com/facebookresearch/segment-anything#model-checkpoints)\n* `CHECKPOINT_FILE`: filename of the Segment Anything model checkpoint file\n* `GPUS`: array of indicies of the GPUs to use, e.g. `[0,1,2,3]``\n\n## Contributing\n\nIf you would like to contribute to SAM Service, feel free to open a pull request. Before doing so, please ensure that your code adheres to the PEP 8 style guide and that all tests pass.\n\n## License\n\nSAM Service is released under the Janelia Open-Source Software License. See `LICENSE` for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaneliascicomp%2Fsam_service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjaneliascicomp%2Fsam_service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaneliascicomp%2Fsam_service/lists"}