Merge branch 'master' into fix-cache-hub-pull

CHANGELOG.md

@@ -214,6 +214,7 @@
 
 
 
+
 
 
 # Change Logs
@@ -14590,3 +14591,31 @@ Jina is released on every Friday evening. The PyPi package and Docker Image will
  - [[```9fee2dff```](https://github.com/jina-ai/jina/commit/9fee2dff341fc5ef3a93f7fdda208ddc9457dd85)] __-__ __docs__: update TOC (*Jina Dev Bot*)
  - [[```fe7b8894```](https://github.com/jina-ai/jina/commit/fe7b8894bc91a4d0d5ec9c255884d89c754189cb)] __-__ __version__: the next version will be 3.7.5 (*Jina Dev Bot*)
 
+<a name=release-note-3-7-6></a>
+## Release Note (`3.7.6`)
+
+> Release time: 2022-08-15 14:04:25
+
+
+
+🙇 We'd like to thank all contributors for this new release! In particular,
+ Han Xiao,  tarrantro,  Zac Li,  Jina Dev Bot,  🙇
+
+
+### 🧼 Code Refactoring
+
+ - [[```49a842d9```](https://github.com/jina-ai/jina/commit/49a842d90a447d0f166ee5218bedabb90d6e0db0)] __-__ unify temp path to dot cache jina (#5058) (*Han Xiao*)
+
+### 📗 Documentation
+
+ - [[```731d492c```](https://github.com/jina-ai/jina/commit/731d492cd02158cac8b5a228bdaaf37855358a11)] __-__ add CPU and GPU type (#5060) (*tarrantro*)
+ - [[```d8f6f418```](https://github.com/jina-ai/jina/commit/d8f6f418877afcc1758d03d6df60d4aca6e1b912)] __-__ rewrite the telemetry session (#5059) (*Han Xiao*)
+ - [[```01111539```](https://github.com/jina-ai/jina/commit/011115394c6e9c2ef7eb7223e61364c92758ddad)] __-__ __jcloud__: autoscale docs (#5056) (*Zac Li*)
+
+### 🍹 Other Improvements
+
+ - [[```299a908b```](https://github.com/jina-ai/jina/commit/299a908bb39ed0c0d6b3f00a5079237c2e2ca7cd)] __-__ __docs__: add what is jina (*Han Xiao*)
+ - [[```23914a81```](https://github.com/jina-ai/jina/commit/23914a81120f73f0b807b70767fbe68a636f0903)] __-__ add what is cross multi modal (*Han Xiao*)
+ - [[```0c78b993```](https://github.com/jina-ai/jina/commit/0c78b993475292987e7ae26f58ba2779377d38f1)] __-__ __docs__: update TOC (*Jina Dev Bot*)
+ - [[```102bc6de```](https://github.com/jina-ai/jina/commit/102bc6defef4c163c145563a343841e667f9f953)] __-__ __version__: the next version will be 3.7.6 (*Jina Dev Bot*)
+

docs/fundamentals/architecture-overview.md

@@ -1,7 +1,7 @@
 (architecture-overview)=
-# Glossary
+# Basic Concepts
 
-This chapter introduces the terminologies you will encounter in the docs. But first, let's look at the code below:
+This chapter introduces the basic terminologies you will encounter in the docs. But first, let's look at the code below:
 
 ````{tab} Server
 ```python
@@ -84,4 +84,17 @@ The following concepts will be covered in the user guide:
 
 **TLS**
     TLS is a security protocol designed to facilitate privacy and data security for communications over the Internet. The communication between {term}`Client` and {term}`Gateway` is protected by TLS.
-```
+```
+
+## Relationship between Jina and DocArray
+
+[DocArray](https://docarray.jina.ai/) is a crucial upstream dependency of Jina. It is the data structure behind Jina. Without DocArray, Jina can not run.
+
+DocArray contains a set of rich API for on the local & monolith development. Jina scales DocArray to the cloud. The picture below shows their relationship.
+
+```{figure} docarray-jina.svg
+```
+
+In a common development journey, a brand-new project first moves horizontally left with DocArray, leveraging all machine learning stacks to improve quality and completing logics in a local environment. At this point, a POC is built. Then move vertically up with Jina, enhancing the POC with service endpoint, scalability and cloud-native features. Finally, you reach to the point where your service is ready for production.
+
+

docs/get-started/what-is.md

@@ -1,3 +1,4 @@
+(intro-cm)=
 # What is Cross-Modal & Multi-Modal?
 
 Jina is the framework for helping you build cross-modal and multi-modal applications on the cloud. But first, what is cross-modal and multi-modal? And what are the applications? This chapter will answer these preliminary questions.
@@ -136,6 +137,6 @@ Don't underestimate the power of this relationship. It is the foundation of neur
 
 In summary, the key of cross-modal and multi-modal application is to understand the relationship between modalities. With the relationship, one can use it to **find existing data**, which is **neural search**; or use it to **make new data**, which is **creative AI**.
 
-In the next chapter, we will see how Jina is the proper tool for building cross-modal and multi-modal applications on the cloud.
+In the {ref}`next chapter<what-is-jina>`, we will see how Jina is the proper tool for building cross-modal and multi-modal applications on the cloud.
 
 

docs/get-started/why-jina.md

@@ -1,4 +1,218 @@
-# Why Jina and Cloud-Native?
+(what-is-jina)=
+# What is Jina?
+
+Jina is the framework for helping you build cross-modal and multi-modal applications on the cloud. With Jina, developers can easily build high performant cloud native applications or services in production. But at this point, you are not buying those campaign words. That's okay and that's what this chapter is about: to tell you what Jina is and to convince you about it.
+
+In the {ref}`last chapter<intro-cm>`, you already learned cross-modal and multi-modal from the machine learning perspective. This chapter will talk more from the system and engineering side. Let's start with an example and understand why Jina is needed.
+
+(motivate-example)=
+## Motivation example
+
+Why do we need Jina? Let's first see an example: an example that describes a life without Jina.
+
+Imagine you are a **machine learning engineer** whose task is to build a shop-the-look service for an e-commerce company, i.e. allowing users to upload a photo and search visually similar items from the stock. Sounds cool and deep learning related, exactly what your expertise is, so let's get started.
+
+### Prototype
+
+There are two mode of the system, one is **indexing**, which is to create the visual representation of all stock items, the other is **search**, which is to take a user-uploaded photo and find the visually similar items from stock.
+
+The indexing part is to create a visual representation of all the stock items. In order to do this, you need to first extract features from the images to create the visual representation. The features could be extracted using a convolutional neural network, and then be stored in a database. 
+
+The search part is to take a user-uploaded photo and find the visually similar items from stock. You first need to extract features from the user-uploaded photo using a convolutional neural network. Then, you can use the similarity metric to find the visually similar items from the stock. The similarity metric could be cosine similarity.
+
+At this point, you need a deep learning framework such as PyTorch, some key-value database such as MongoDB, and possibly some vector search engine such as FAISS or Elasticsearch. As a machine learning engineer, you are probably most familiar with PyTorch. But you are smart and full of energy so nothing you can't learn. You easily glue them together.
+
+### As a service
+
+Are we done? Not quite yet. Instead of some Python functions, your goal is to make it as a web service so that its IO goes through network. To do that, you need to _refactor_ the above logic in some web framework with some API so that it can be called by other services.
+
+There are many ways to do this, one example would be to use the Django web framework. You would create an endpoint that accepts user-uploaded photos, then use the above logic to find the visually similar items from stock. Finally, you would return the results to the user in the form of a JSON object.
+
+At this point, you learned few new things such as REST API, web service, web framework, which seems to go beyond your scope of a "machine learning engineer". You started to wonder whether it is worth it to learn them. But you are a machine learning **engineer** after all, so you decided to learn. But deep down you feel that your engineering may not be sufficient to make it into production. After some time, you managed to glue everything together.
+
+### Deployment
+
+Product team is impressed by the progress and asks you to deploy it on AWS to serve some real traffic. You encountered many problems while migrating from local to the cloud, mostly because of dependencies issues, CUDA driver and GPU issues. You finally solved all of them by wrapping everything in a 30GB Docker image. It is a _big_ monolith container, but it is easy to deploy and manage for you. 
+
+### Scalability and performance
+
+Are we done now? Still not quite yet. The product team wants to ensure certain scalability of the service in practice, meaning that the feature extraction should be parallelized and concurrent user requests should be handled without lagging. Certain QPS (query per second) is required from the product team.
+
+You tried with straightforward `multiprocessing` or `threading`, but nothing works out of the box with your deep learning stacks. You decided to learn more high-performance computing frameworks such as Dask or Ray and try to adopt them. After some trial and error, you finally glued everything together and made them work. At this point you feel exhausted as it diverges too far from your expertise. 
+
+### Availability and downtime
+
+_"What if our database is down (due to update) for a short-time?"_
+
+So you designed some naive failsafe mechanism that you just learned from a blog post. You also picked up some AWS service in a rush to ensure the availability of the service, hoping it can be fire-and-forget.
+
+### Observability
+
+_"How can I see the incoming traffic?"_
+
+You changed all `print` to `logger.info` and impatiently spin up a dashboard.
+
+### Security
+
+_"Can we add some authentication header to it?"_
+
+_"Is this service prone to attack?"_
+
+At this point, you are burnt out. It goes too far from your expertise. You decided to hand over the project to a senior backend engineer, who is a new hire but has a lot of experience in infrastructure engineering and cloud services. He knows what he is doing and is willing to help you.
+
+So you sit down with him, scrolling over your glued code and justifying all your tricks, design decisions and caveats. He kept nodding. Soon after he took a slow and thoughtful sip of his coffee, he said: 
+
+"Why don't we start to rewrite it?"
+
+## Problems and Jina's solution
+
+The above example is quite real, and it reveals some gaps when developing a cross-modal/multi-modal system in production:
+
+**First is the lack of design pattern for such system.** It is unclear how should one represent, compute, store, and transit the data with different modalities in a consistent way; and how can one switch between different tools and avoid glue code. 
+
+**Second is the large gap of between a proof-of-concept and a production system.** For a production system, cloud native techniques are often required to ensure the professionalism and scalability of the system. In particular, microservices, orchestration, containerization and observability are four pillars of such system. However, the learning curve is too steep for many machine learning engineers.
+
+**Third is the long go-to-market time**. If a company chooses a wrong tech stack, it will take longer to bring the product to market. This is because the company will have to spend more time and resources on developing the product, refactoring it, going back and forth. In addition, a wrong stack can cause problems with the product itself, raising the risk of the product being unsuccessful.
+
+Jina is a solution to address above problems by providing a consistent design pattern for cross-modal/multi-modal systems with latest cloud native technologies.
+
+### Why cloud native?
+
+Cloud native is a term that refers to a system that is designed to run on the cloud. It consists of a group of concepts:
+- **Microservices**: Microservices are the core of a cloud-native system. They are the building blocks of a cloud-native system.
+- **Orchestration**: Orchestration is the process of managing the microservices.
+- **Containerization**: Containerization is the process of packaging the microservices into containers.
+- **Observability**: Observability is the process of monitoring the system.
+- **DevOps and CI/CD**: DevOps and CI/CD are the process of automating the system.
+
+Sounds cool, But do we really need them?
+
+Yes!
+
+| Characteristics of a cross-modal/multi-modal system                                                                                                                  | How would Cloud-native help                                                                                          |
+|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
+| Cross-modal/multi-modal system is not a single task, it usually consists of multiple components and forms a workflow or multiple workflows (e.g. indexing and search) | **Microservice** each task, then **orchestrate** them into workflows.                                                |
+| Cross-modal/multi-modal system involves complicated package dependencies.                                                                                            | **Containerization** comes to help to ensure the reproducibility and isolation.                                      |
+| Cross-modal/multi-modal system is often a backend/infrastructure service that requires extra stablilty.                                                              | **DevOps and CI/CD** guarantees the integration and **Observability** provides the health information of the system. |
+
+
+With that, let me reiterate what Jina is: Jina is a framework that provides a unified, cloud native solution for building cross-modal/multi-modal systems from day one. It provides the best developer experience from day one POC to production. It smooths your journey by resolving every subsection mentioned in {ref}`motivate-example`. No more tech debt, no more refactoring and back and forth between different systems.
+
+Now it starts to make sense, right? Let's get our first taste on how Jina project looks like and how does it work.
+
+## Taste of Jina
+
+Let's look at a simple Jina hello world example. We write a function that appends `"hello, world"` to a Document, we apply the function twice for the two Documents, then return and print their texts.
+
+````{tab} With Jina
+```python
+from jina import DocumentArray, Executor, Flow, requests
+
+
+class MyExec(Executor):
+    @requests
+    async def foo(self, docs: DocumentArray, **kwargs):
+        for d in docs:
+            d.text += 'hello, world!'
+
+
+f = Flow().add(uses=MyExec).add(uses=MyExec)
+
+with f:
+    r = f.post('/', DocumentArray.empty(2))
+    print(r.texts)
+```
+
+```console
+────────────────────────── 🎉 Flow is ready to serve! ──────────────────────────
+╭────────────── 🔗 Endpoint ───────────────╮
+│  ⛓     Protocol                    GRPC  │
+│  🏠       Local           0.0.0.0:52570  │
+│  🔒     Private     192.168.1.126:52570  │
+│  🌍      Public    87.191.159.105:52570  │
+╰──────────────────────────────────────────╯
+
+['hello, world!hello, world!', 'hello, world!hello, world!']
+```
+
+````
+````{tab} Plain Python
+```python
+class Document:
+    text: str = ''
+
+
+def foo(docs, **kwargs):
+    for d in docs:
+        d.text += 'hello, world!'
+
+
+docs = [Document(), Document()]
+foo(docs)
+foo(docs)
+for d in docs:
+    print(d.text)
+```
+
+
+```console
+['hello, world!hello, world!', 'hello, world!hello, world!']
+```
+````
+
+It is a pretty straightforward program. It abstracts away the complexity of a real cross-modal & multi-modal system, leaving only the basic logics: make a data structure, operate on it, and return the result. 
+
+In fact, one can achieve the same in 14 lines of code (`black`ed) with pure Python.
+
+So does using Jina means some special design pattern that needs one extra line of code to achieve the same result with pure Python? What's the deal?
+
+Here is the deal. The features below come out of the box with the above 15 lines of code:
+
+- Replicas, sharding, scalability in just one line of code;
+- Client/server architecture with duplex streaming;
+- Async non-blocking data workflow;
+- gRPC, Websockets, HTTP, GraphQL gateway support;
+- Microservice from day one, Docker containerization seamlessly;
+- Explicit version and dependency control;
+- Reuse building blocks from Hub marketplace;
+- Immediate observability via Prometheus and Grafana;
+- Kubernetes seamless integration.
+
+If you think that's a lot of over-promises, it is not. In fact, they barely scratch the surface of Jina's capability.
+
+## Design principles
+
+With so many powerful features, the learning curve of Jina must be very steep, you might think. But it is not. In fact, you only need to know three concepts to master Jina. They are Document, Executor and Flow, which are introduced in {ref}`architecture-overview`.
+
+A full-fledged cross-model/multi-model system is a combination of the following seven layers:
+
+```{figure} 7-layers.png
+:scale: 50%
+```
+
+This illustration is not exaggerating, it is a real-world example of a cross-modal/multi-modal system in production.
+
+Fortunately, as a Jina developer, you don't need to understand all of them. You only need to know what are relevant to your product logic and let Jina handles the rest. In particular, 
+
+- **The data type**: represents the common data structure across the system; this corresponds to "**Document**" in Jina.
+- **The logics**: represents the product logic of each component; this corresponds to "**Executor**" in Jina.
+- **The orchestration**: represents the workflow of all components; this corresponds to "**Flow**" in Jina.
+
+are all you need.
+
+```{figure} 3-layers.png
+:scale: 50%
+```
+
+Patterns are nice, cloud native features are awesome. But what's the point if you need to spend months to learn them? Jina's design principles are simple and clear: flatten the learning curve for Python developers and make all awesome production-level features easily accessible.
+
+
+## Summary
+
+Before Jina, building a cross-modal/multi-modal system was a tedious and time-consuming process. It involved a lot of glue code, back and forth refactoring and after months you eventually end up with a fragile system that is unsustainable. With Jina, you are doing it professionally from day one: from POC to production; from deployment to scaling; from monitoring to analytics; everything is taken care of by Jina. We know the pain, we have the lessons learned and that's why we build Jina: to make developing cross-modal and multi-modal system an easier, productive and enjoyable experience for you.
+
+
+
 
 
 

docs/index.md

@@ -61,6 +61,7 @@ If you'd like to opt out of usage statistics, make sure to add the `--optout-tel
 :hidden:
 
 get-started/what-is
+get-started/why-jina
 fundamentals/architecture-overview
 get-started/install/index
 get-started/create-app