{"id":28956954,"url":"https://github.com/developmentseed/segment-anything-services","last_synced_at":"2025-07-29T04:09:09.480Z","repository":{"id":153645428,"uuid":"624654348","full_name":"developmentseed/segment-anything-services","owner":"developmentseed","description":"Running segment-anything image embedding, prompting, and mask generation as torchserve services","archived":false,"fork":false,"pushed_at":"2024-10-10T07:26:12.000Z","size":47482,"stargazers_count":95,"open_issues_count":6,"forks_count":11,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-06-23T21:47:26.411Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/developmentseed.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}},"created_at":"2023-04-07T00:34:35.000Z","updated_at":"2025-03-29T12:29:08.000Z","dependencies_parsed_at":"2023-10-11T12:15:34.309Z","dependency_job_id":"81f8a5c6-4165-49ba-b22d-798f9027ded6","html_url":"https://github.com/developmentseed/segment-anything-services","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/developmentseed/segment-anything-services","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developmentseed%2Fsegment-anything-services","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developmentseed%2Fsegment-anything-services/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developmentseed%2Fsegment-anything-services/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developmentseed%2Fsegment-anything-services/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/developmentseed","download_url":"https://codeload.github.com/developmentseed/segment-anything-services/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developmentseed%2Fsegment-anything-services/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267626986,"owners_count":24117709,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-29T02:00:12.549Z","response_time":2574,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":"2025-06-23T21:41:15.242Z","updated_at":"2025-07-29T04:09:09.458Z","avatar_url":"https://github.com/developmentseed.png","language":"Jupyter Notebook","readme":"# Deprecation Notice\nThis has been deprecated, check out the new open source backend for the geospatial imagery annotation tool [DS-Annotate](https://github.com/developmentseed/ds-annotate), https://github.com/GeoCompas/samgeo-service by [GeoCompas](https://geocompas.ai/)!\n\n# Segment Anything Encoder and Decoder as Services\n\n![Oil slick captured by Sentinel-1 Segmented](slick_example.png)\n\n![Burn Scar captured by Sentinel-2 Segmented](burn_scar_sam_example.png)\n\n\n## Quickstart\n\n### Building the container for creating the .mar archives\n\nBoth models will be downloaded using the vit_h weights.\n\n```\ndocker build -t sam-builder -f Dockerfile-build .\n```\n\n### Copying the .mar archives to host for local testing\n\n```\ndocker run -d --name sam-builder1 sam-builder\ndocker cp sam-builder1:/home/model-store ./\n```\n\nWe copy these to model-store and use this locally by both the GPU and the CPU Torchserve containers.\n\nyou can delete the container once models are copied\n\n```\ndocker rm -f sam-builder1\n```\n\n### Building the gpu torchserve container for image encoding\nWith the GPU, inference time should be about 1.8 seconds or less depending on the GPU. On an older 1080 Ti Pascal GPU, inference time is 1.67 seconds without compilation.\n\n```\ndocker build -t sam-gpu -f Dockerfile-gpu .\nbash start_serve_encode_gpu.sh\n```\n\n### Building the cpu torchserve container for image decoding\n\n```\ndocker build -t sam-cpu -f Dockerfile-cpu .\nbash start_serve_decode_cpu.sh\n```\n\n### Test the encode service on the CPU\n\nThe CPU service is served on 7080 by default. 8080 for the GPU service by default.\n\n```\ncurl http://127.0.0.1:7080/predictions/sam_vit_h_encode -T ./data/sample-img-fox.jpg\n```\n\n### Testing\n\nAll tests in `tests/` cover the functionality of the decoder. Logic in `decode.py` is run in pytest fixtures within `conftest.py` when outputs need to be shared by different tests in `test_decode.py`.\n\nTo start running the tests, make sure you have the test models. You should have the same models used during inference, including\n\n```\n(test.py3.10) (base) rave@rave-desktop:~/segment-anything-services/tests/models$ tree\n.\n├── sam_vit_h_4b8939.pth\n└── sam_vit_h_decode.onnx\n```\n\nYou can get both by unzipping the .mar archives copied to `model-store` from the sam-builder container you started in the previous step. Then, move the .onnx and the .pth files to ./tests/models/\n\n```\nunzip model-store/sam_vit_h_decode.mar -d ./sam_decode_mar\nunzip model-store/sam_vit_h_encode.mar -d ./sam_encode_mar\ncp ./sam_decode_mar/sam_vit_h_decode.onnx ./tests/models/\ncp ./sam_decode_mar/sam_vit_h_4b8939.pth ./tests/models/\n```\n\nInstall the testing environment with [hatch](https://hatch.pypa.io/latest/install/): `pip install hatch`\n\nThen, create the environment. I tested with Python 3.10, Python 3.11 does not work because of an onnxruntime version issue.\n\n`hatch -e test.py3.10 shell`\n\nThen, run tests with pytest\n\n```\npytest tests\n```\n\n## Local Setup without Docker\n\n### 1. Downloading model weights\n\nIf you have access, download from the devseed s3:\n\n```\naws s3 sync s3://segment-anything/model-weights/ model-weights\n```\n\notherwise, get checkpoints from the original repo: https://github.com/facebookresearch/segment-anything/tree/main#model-checkpoints\n\n\n### 2a. Package the torch weights for GPU encoding\n\nThis step takes a long time presumably because the uncompiled weights are massive. Packaging the ONNX model is faster in the later steps.\n\n```\nmkdir -p model_store_encode\ntorch-model-archiver --model-name sam_vit_h_encode --version 1.0.0 --serialized-file model-weights/sam_vit_h_4b8939.pth --handler handler_encode.py\nmv sam_vit_h_encode.mar model_store_encode/sam_vit_h_encode.mar\n```\n\n### 2b. Exporting the ONNX model for CPU decoding\n\n```\nmkdir -p models\npython scripts/export_onnx_model.py --checkpoint model-weights/sam_vit_h_4b8939.pth --model-type vit_h --output models/sam_vit_h_decode.onnx\n```\n\n### 2c. Package the ONNX model for CPU decoding with the handler\n\nWe'll put this in the model_store_decode directory, to keep the onnx model files distinct from the torchserve .mar model archives. model_store/ is created automatically by Torchserve in the container, which is why we're make a local folder here called \"model_store_decode\".\n\n```\nmkdir -p model_store_decode\ntorch-model-archiver --model-name sam_vit_h_decode --version 1.0.0 --serialized-file models/sam_vit_h_decode.onnx --handler handler_decode.py\nmv sam_vit_h_decode.mar model_store_decode/sam_vit_h_decode.mar\n```\n\n### Building jupyter server container\n\nUse this container to test the model in a GPU enabled jupyter notebook server with geospatial and pytorch dependencies installed.\n\n```\ndocker build -t sam-dev -f Dockerfile-dev .\n```\n\n### 5. Test the endpoints\n\nYou can run `test_endpoint.ipynb` to then use the two running services you started above. The dependencies are minimal for this notebook, install them on your own or you can run them in the jupyter server below.\n\n### 6. Run jupyter server container\n\nThis is a GPU enabled container that is set up with SAM and some other dependencies we commonly use. You can use it to try out SAM model in a notebook environment. Remove the `--gpus` arg if you don't have a GPU.\n\n```\ndocker run -it --rm \\\n    -v $HOME/.aws:/root/.aws \\\n    -v \"$(pwd)\":/segment-anything-services \\\n    -p 8888:8888 \\\n    -e AWS_PROFILE=devseed \\\n    --gpus all sam-dev\n```\n\n## Deployment\n\n1. Install the dependencies to deploy from npm\n\n```\nnpm install -g @openaddresses/deploy\n```\n2. Set up your credentials by navigating to the AWS SSO login page, and selecting \"Command Line Access\" to copy the temporary credentials. paste these to `~/.aws/credentials` and rename the AWS profile (ask Ryan for this.)\n3. `touch ~/.deployrc.json` and fill it with\n```\n   {\n    \"profilename\": {\n        \"region\": \"us-east-1\"\n    }\n}\n```\n4. run deploy init to generate a `.deployrc.json` config for the repo. both the local and global config are needed to deploy. Fill in args when prompted based on the profile name\n5. commit and make a PR with any changes. wait for all github actions to complete so that the model archives and docker images are built\n6. `deploy update prod` to deploy changes to prod\n\n\n### (Potentially) Frequently Asked Questions\nQ: What GPUs was this tested with?\n\nA: The encoder and decoder are tested locally with a 1080 Ti (Pascal) and 3090 (Ampere). In production, the encoder runs on a p3.2xlarge (Tesla V100). Older Kepler GPUs such as K80s are not tested. See [this issue](https://github.com/developmentseed/segment-anything-services/issues/36) for guidance on adapting the docker images to work with Kepler series GPUs.\n\nQ: Why two services?\n\nA: We're exploring cost effective ways to run image encoding in a separate, on-demand way from the CPU decoder. Eventually we'd like to remove the need for the CPU torserve on the backend and run the decoding in the browser.\n\nQ: Can I contribute or ask questions?\n\nA: This is currently more of a \"working in the open\" type repo that we'd like to share with others, rather than a maintained project. But feel free to open an issue if you have an idea. Please understand if we don't respond or are slow to respond.\n\n### Contributing and packaging\n\nWe use hatch to build the sam-serve package. This wheel file is built from source when building the cpu or gpu docker images. We also use hatch to publish the package to PYPI. We don't have CI CD yet, so if you are interested in contributing, increment the version in your PR and notify the maintainers @rbavery or @rub21 and we will publish the package on PR merge.\n\nThe main commands are\n\n`hatch build` to make the whl file\n\n`hatch publish` to publish a release\n\nhatch can be installed with pip or pipx\n\n`pip install hatch`\n\n## License\n\nThe model and code is licensed under the [Apache 2.0 license](LICENSE).\n\n## References\n\nKirillov, A., Mintun, E., Ravi, N., Mao, H., Rolland, C., Gustafson, L., ... Girshick, R. (2023). Segment Anything. *arXiv:2304.02643*. https://github.com/facebookresearch/segment-anything\n\nThe scripts/export_onnx_model.ipynb and notebooks/sam_onnx_model_example_fox.ipynb are from the original repo.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevelopmentseed%2Fsegment-anything-services","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevelopmentseed%2Fsegment-anything-services","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevelopmentseed%2Fsegment-anything-services/lists"}