diff --git a/README.md b/README.md index cbb79461ed8..9253bc06040 100644 --- a/README.md +++ b/README.md @@ -14,21 +14,21 @@ -DocArray is a library for nested, unstructured, multimodal data in transit, including text, image, audio, video, 3D mesh, etc. It allows deep-learning engineers to efficiently process, embed, search, recommend, store, and transfer the multi-modal data with a Pythonic API. +DocArray is a library for nested, unstructured, multimodal data in transit, including text, image, audio, video, 3D mesh, etc. It allows deep-learning engineers to efficiently process, embed, search, recommend, store, and transfer multimodal data with a Pythonic API. -πŸšͺ **Door to cross-/multi-modal world**: super-expressive data structure for representing complicated/mixed/nested text, image, video, audio, 3D mesh data. The foundation data structure of [Jina](https://github.com/jina-ai/jina), [CLIP-as-service](https://github.com/jina-ai/clip-as-service), [DALLΒ·E Flow](https://github.com/jina-ai/dalle-flow), [DiscoArt](https://github.com/jina-ai/discoart) etc. +πŸšͺ **Door to multimodal world**: super-expressive data structure for representing complicated/mixed/nested text, image, video, audio, 3D mesh data. The foundation data structure of [Jina](https://github.com/jina-ai/jina), [CLIP-as-service](https://github.com/jina-ai/clip-as-service), [DALLΒ·E Flow](https://github.com/jina-ai/dalle-flow), [DiscoArt](https://github.com/jina-ai/discoart) etc. πŸ§‘β€πŸ”¬ **Data science powerhouse**: greatly accelerate data scientists' work on embedding, k-NN matching, querying, visualizing, evaluating via Torch/TensorFlow/ONNX/PaddlePaddle on CPU/GPU. 🚑 **Data in transit**: optimized for network communication, ready-to-wire at anytime with fast and compressed serialization in Protobuf, bytes, base64, JSON, CSV, DataFrame. Perfect for streaming and out-of-memory data. -πŸ”Ž **One-stop k-NN**: Unified and consistent API for mainstream vector databases that allows nearest neighboour search including Elasticsearch, Redis, ANNLite, Qdrant, Weaviate. +πŸ”Ž **One-stop k-NN**: Unified and consistent API for mainstream vector databases that allows nearest neighbor search including Elasticsearch, Redis, AnnLite, Qdrant, Weaviate. -πŸ‘’ **For modern apps**: GraphQL support makes your server versatile on request and response; built-in data validation and JSON Schema (OpenAPI) help you build reliable webservices. +πŸ‘’ **For modern apps**: GraphQL support makes your server versatile on request and response; built-in data validation and JSON Schema (OpenAPI) help you build reliable web services. -🐍 **Pythonic experience**: designed to be as easy as a Python list. If you know how to Python, you know how to DocArray. Intuitive idioms and type annotation simplify the code you write. +🐍 **Pythonic experience**: as easy as a Python list. If you can Python, you can DocArray. Intuitive idioms and type annotation simplify the code you write. -πŸ›Έ **Integrate with IDE**: pretty-print and visualization on Jupyter notebook & Google Colab; comprehensive auto-complete and type hint in PyCharm & VS Code. +πŸ›Έ **IDE integration**: pretty-print and visualization on Jupyter notebook and Google Colab; comprehensive autocomplete and type hints in PyCharm and VS Code. Read more on [why should you use DocArray](https://docarray.jina.ai/get-started/what-is/) and [comparison to alternatives](https://docarray.jina.ai/get-started/what-is/#comparing-to-alternatives). @@ -61,9 +61,9 @@ DocArray consists of three simple concepts: Let's see DocArray in action with some examples. -### Example 1: represent multimodal data in dataclass +### Example 1: represent multimodal data in a dataclass -The following news article card can be easily represented via `docarray.dataclass` and type annotation: +You can easily represent the following news article card with `docarray.dataclass` and type annotation: @@ -104,9 +104,9 @@ d = Document(a)
-### Example 2: a 10-liners text matching +### Example 2: text matching in 10 lines -Let's search for top-5 similar sentences of she smiled too much in "Pride and Prejudice". +Let's search for top-5 similar sentences of she smiled too much in "Pride and Prejudice": ```python from docarray import Document, DocumentArray @@ -137,7 +137,7 @@ Here the feature embedding is done by simple [feature hashing](https://en.wikipe ### Example 3: external storage for out-of-memory data -When your data is too big, storing in memory is probably not a good idea. DocArray supports [multiple storage backends](https://docarray.jina.ai/advanced/document-store/) such as SQLite, Weaviate, Qdrant and ANNLite. They are all unified under **the exact same user experience and API**. Take the above snippet as an example, you only need to change one line to use SQLite: +When your data is too big, storing in memory is not the best idea. DocArray supports [multiple storage backends](https://docarray.jina.ai/advanced/document-store/) such as SQLite, Weaviate, Qdrant and AnnLite. They're all unified under **the exact same user experience and API**. Take the above snippet: you only need to change one line to use SQLite: ```python da = DocumentArray( @@ -146,15 +146,13 @@ da = DocumentArray( ) ``` -The code snippet can still run **as-is**. All APIs remain the same, the code after are then running in a "in-database" manner. +The code snippet can still run **as-is**. All APIs remain the same, the subsequent code then runs in an "in-database" manner. -Besides saving memory, one can leverage storage backends for persistence, faster retrieval (e.g. on nearest-neighbour queries). +Besides saving memory, you can leverage storage backends for persistence and faster retrieval (e.g. on nearest-neighbor queries). +### Example 4: complete workflow of visual search - -### Example 4: a complete workflow of visual search - -Let's use DocArray and the [Totally Looks Like](https://sites.google.com/view/totally-looks-like-dataset) dataset to build a simple meme image search. The dataset contains 6,016 image-pairs stored in `/left` and `/right`. Images that share the same filename are perceptually similar. For example: +Let's use DocArray and the [Totally Looks Like](https://sites.google.com/view/totally-looks-like-dataset) dataset to build a simple meme image search. The dataset contains 6,016 image-pairs stored in `/left` and `/right`. Images that share the same filename appear similar to the human eye. For example: @@ -175,11 +173,11 @@ Let's use DocArray and the [Totally Looks Like](https://sites.google.com/view/to
-Our problem is given an image from `/left`, can we find its most-similar image in `/right`? (without looking at the filename of course). +Given an image from `/left`, can we find the most-similar image to it in `/right`? (without looking at the filename). ### Load images -First we load images. You *can* go to [Totally Looks Like](https://sites.google.com/view/totally-looks-like-dataset) website, unzip and load images as below: +First we load images. You *can* go to [Totally Looks Like](https://sites.google.com/view/totally-looks-like-dataset)'s website, unzip and load images as below: ```python from docarray import DocumentArray @@ -187,19 +185,19 @@ from docarray import DocumentArray left_da = DocumentArray.from_files('left/*.jpg') ``` -Or you can simply pull it from Jina Cloud: +Or you can simply pull it from Jina AI Cloud: ```python left_da = DocumentArray.pull('jina-ai/demo-leftda', show_progress=True) ``` **Note** -If you have more than 15GB of RAM and want to try using the whole dataset instead of just the first 1000 images, remove [:1000] when loading the files into the DocumentArrays left_da and right_da. +If you have more than 15GB of RAM and want to try using the whole dataset instead of just the first 1,000 images, remove `[:1000]` when loading the files into the DocumentArrays `left_da` and `right_da`. -You will see a running progress bar to indicate the downloading process. +You'll see a progress bar to indicate how much has downloaded. -To get a feeling of the data you will handle, plot them in one sprite image. You will need to have matplotlib and torch installed to run this snippet: +To get a feeling of the data, we can plot them in one sprite image. You need matplotlib and torch installed to run this snippet: ```python left_da.plot_image_sprites() @@ -232,7 +230,7 @@ Did I mention `apply` works in parallel? ### Embed images -Now convert images into embeddings using a pretrained ResNet50: +Now let's convert images into embeddings using a pretrained ResNet50: ```python import torchvision @@ -245,7 +243,7 @@ This step takes ~30 seconds on GPU. Beside PyTorch, you can also use TensorFlow, ### Visualize embeddings -You can visualize the embeddings via tSNE in an interactive embedding projector. You will need to have pydantic, uvicorn and fastapi installed to run this snippet: +You can visualize the embeddings via tSNE in an interactive embedding projector. You will need to have pydantic, uvicorn and FastAPI installed to run this snippet: ```python left_da.plot_embeddings(image_sprites=True) @@ -255,8 +253,7 @@ left_da.plot_embeddings(image_sprites=True) Visualizing embedding via tSNE and embedding projector

-Fun is fun, but recall our goal is to match left images against right images and so far we have only handled the left. Let's repeat the same procedure for the right: - +Fun is fun, but our goal is to match left images against right images, and so far we have only handled the left. Let's repeat the same procedure for the right: @@ -289,9 +286,9 @@ right_da = (
-### Match nearest neighbours +### Match nearest neighbors -We can now match the left to the right and take the top-9 results. +Now we can match the left to the right and take the top-9 results. ```python left_da.match(right_da, limit=9) @@ -312,7 +309,7 @@ left/02262.jpg right/04520.jpg 0.16477376 ... ``` -Or shorten the loop as one-liner using the element & attribute selector: +Or shorten the loop to a one-liner using the element and attribute selector: ```python print(left_da['@m', ('uri', 'scores__cosine__value')]) @@ -337,7 +334,7 @@ Better see it. Visualizing top-9 matches using DocArray API

-What we did here is revert the preprocessing steps (i.e. switching axis and normalizing) on the copied matches, so that you can visualize them using image sprites. +Here we reversed the preprocessing steps (i.e. switching axis and normalizing) on the copied matches, so you can visualize them using image sprites. ### Quantitative evaluation @@ -350,7 +347,7 @@ groundtruth = DocumentArray( ) ``` -Here we create a new DocumentArray with real matches by simply replacing the filename, e.g. `left/00001.jpg` to `right/00001.jpg`. That's all we need: if the predicted match has the identical `uri` as the groundtruth match, then it is correct. +Here we created a new DocumentArray with real matches by simply replacing the filename, e.g. `left/00001.jpg` to `right/00001.jpg`. That's all we need: if the predicted match has the identical `uri` as the groundtruth match, then it is correct. Now let's check recall rate from 1 to 5 over the full dataset: @@ -372,25 +369,23 @@ recall@4 0.052194148936170214 recall@5 0.0573470744680851 ``` -More metrics can be used such as `precision_at_k`, `ndcg_at_k`, `hit_at_k`. +You can also use other metrics like `precision_at_k`, `ndcg_at_k`, `hit_at_k`. -If you think a pretrained ResNet50 is good enough, let me tell you with [Finetuner](https://github.com/jina-ai/finetuner) you could do much better in just 10 extra lines of code. [Here is how](https://finetuner.jina.ai/notebooks/image_to_image/). +If you think a pretrained ResNet50 is good enough, let me tell you with [Finetuner](https://github.com/jina-ai/finetuner) you can do much better with [just another ten lines of code](https://finetuner.jina.ai/notebooks/image_to_image/). ### Save results -You can save a DocumentArray to binary, JSON, dict, DataFrame, CSV or Protobuf message with/without compression. In its simplest form, +You can save a DocumentArray to binary, JSON, dict, DataFrame, CSV or Protobuf message with/without compression. In its simplest form: ```python left_da.save('left_da.bin') ``` -To reuse it, do `left_da = DocumentArray.load('left_da.bin')`. - +To reuse that DocumentArray's data, use `left_da = DocumentArray.load('left_da.bin')`. If you want to transfer a DocumentArray from one machine to another or share it with your colleagues, you can do: - ```python left_da.push('my_shared_da') ``` @@ -406,7 +401,7 @@ Intrigued? That's only scratching the surface of what DocArray is capable of. [R ## Support -- Join our [Slack community](https://slack.jina.ai) and chat with other community members about ideas. +- Join our [Slack community](https://jina.ai/slack) and chat with other community members about ideas. > DocArray is a trademark of LF AI Projects, LLC